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INTRODUCTION 

The 8K Programming System PS/8, is an extremely powerful 
program development system. PS/8 greatly expands the capa- 
bilities of any 8K PDP-8, 8/1, 8/L, 8/E, or PDP-12 computer 
having the necessary disk or DECtape storage. Use of PS/8 
is described in detail in the 8K Programming System User's 
Guide , with which the reader should be familiar. 

This manual covers a wide range of advanced topics pertinent 
to the experienced user. In Chapter 1 the various basic 
system concepts are described and terms defined. Chapter 2 
explains the process by which user programs call upon the 
system for the performance of important operations; includ- 
ing loading device handlers, opening and closing files, and 
chaining to other programs . Chapter 3 covers the functions 
of the Command Decoder and the means by which the user program 
can employ its services. Chapter 4 explains the use and opera- 
tion of the device handlers in detail. Chapter 5 covers the 
details of "custom tailoring" a system, including how to 
write a device handler for a non-standard device. 

Technical information, intended to enhance the information in 
the 8K Programming System User's Guide as well as this manual, 
can be found in the Appendices. Appendix A details the PS/8 
directory structure and gives standard file formats. Appendix 
B describes the system data base and gives the layouts of the 
system areas. Appendix C gives a complete list of system error 
messages. Appendix D illustrates some useful advanced techniques 
and programming "tricks" for use with the PS/8 system. Appendix 
E is a complete list of the standard ASCII character codes mean- 
ingful to PS/8. Finally, Appendix F contains additions to the 
8K Programming System User's Guide, sections covering the CREF 
and Library Setup programs that will be included in later edi- 
tions of the User's Guide. 
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PS/8 does not attempt to solve all problems. Since it runs 
with the interrupt disabled, any calls to the system must be 
made with the interrupt turned off. Nonetheless, PS/8 pro- 
vides a powerful means to solve the most frequently encountered 
problems in developing software for PDP-8 family computers. 



VI 



CHAPTER 1 



PS/8 CONCEPTS AND TERMINOLOGY 



Before examining the details of the PS/8 system the reader 
should first be familiar with the simpler techniques and terms 
used within the framework of the PS/8 system. The material in 
this chapter, along with that contained in the 8K Programming 
System User's Guide , provides the tools needed to pursue the 
later chapters . 

1.1 Software Componenets of PS/8 

There are four main components of the PS/8 system: 

a. The Keyboard Monitor performs commands specified by 
the user at the console. The nine Keyboard Monitor 
commands (ASSIGN, DEASSIGN, GET, SAVE, ODT, RUN, R, 
START, and DATE) are explained in Chapter 2 of the 8K 
Programming System User's Guide . 

User programs can exit to the Keyboard Monitor by 
executing a JMP to location 7600 in field 0. 

NOTE 

All JMPs to 7600 must be made 
with the DATA FIELD set to zero. 

This saves the contents of location to 1777 in field 
and loads the Keyboard Monitor which could be called 
by a JMP to location 7605 in field 0. In this latter 
case the contents of core are not saved, which conserves 
some time . 

Existing system programs, device handlers, and the Command 
Decoder test for the CTRL/C character in the Teletype* 
input buffer and on finding this character abort the 
current operation and perform a JMP to 7600 in field 0. 
Thus, typing CTRL/C is the conventional method of call- 
ing the Keyboard Monitor from the console. 



*Teletype is a registered trademark of the Teletype Corporation. 
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b. Device handlers, which are subroutines for perform- 
ing all device-oriented input/output operations, 
can be utilized by any program. These subroutines 
have standard calling sequences and "mask" from the 
user program the special characteristics of the I/O 
device. In this way, device independent I/O is 
achieved. A detailed description of device handlers 
is found in Chapter 4. 

c. The User Service Routine (USR) is to a program what 
the Keyboard Monitor is to the user. For example, 
programs can request the USR to fetch device handlers, 
perform file operations on any device, chain to another 
program, or call the Command Decoder. A full descrip- 
tion of the USR functions is found in Chapter 2. 

d. The Command Decoder interprets a command line typed 
by the user to indicate input and output files and 
various options. The command line format is described 
in detail in Chapter 3 of the 8K Programming System 
User's Guide . The Command Decoder removes the burden 
of this repetitive operation from the user's progrtim. 
A full description of the Command Decoder's function 
is found in Chapter 3. 

1.2 Files 

Files are basic units of the PS/8 system, and a thorough under- 
standing of file structure is required for its use. A file 
is any collection of data to be treated as a unit. The format 
of this data is unimportant; for example, PS/8 can manipulate 
several standard formats, including ASCII files, binary files, 
and core image files. The important consideration is that 
the data forms a single unit within the system. 

1.2.1 File Names and Extensions 

An individual file is identified by its file name and extension. 
The file name consists of up to six alphanumeric characters, 
optionally followed by a two character extension. The extension 
is often used to clarify the format of the data within the file. 
For example, an ASCII file used as input to PALS might be given 
a .PA extension, while a core image file has a .SV extension. 



1-2 



1.2.2 File Structured Devices 

Devices that can be logically divided into a number of 256 
word blocks and have the ability to read and write from any 
desired block are called file structured devices. Disks and 
DECtapes are file structured devices while a paper tape reader 
or Teletype is not. 

The system device (SYS:) in any PS/8 system is always file 
structured. 

All PS/8 file structured devices must be logically divided 
into these 256 word blocks. Hence, 256 words is considered 
the standard PS/8 block size. Some devices, like RK8, DEC- 
tape, and LINCtape, are physically divided into blocks. 
These physical blocks should not be confused with the logical 
256-word blocks. For example, DECtapes must be formatted with 
standard 129 word physical blocks. A logical PS/8 block con- 
sists of the first 128 words of two consecutive physical DEC- 
tape blocks. The 129th word of every DECtape block is not 
used by PS/8. Similarly, LINCtapes are formatted with 129 
(or 128) words per block but never 256, as this format is 
unacceptable to PS/8. 

A given PS/8 file consists of one or more sequential blocks 
of 256 words each (consecutively numbered) . A minimum of one 
block per file is required, although a single file could 
occupy all of the blocks on a device. 

1.2.3 File Types 

Three different types of files exist in the PS/8 system: 



An empty file is a contiguous area of unused blocks, 
Empty files are created when permanent files are 
deleted. 
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b. A tentative file is a file that is open to accept 
output and has not yet been closed. Only one tenta- 
tive file can be open on any single device at one 
time. 

c. A permanent file is a file that has been given a 
fixed size and is no longer expandable. A tenta- 
tive file becomes permanent when it is closed. 

To further understand file types, consider what occurs when 
a file is created. Normally, the User Service Routine in 
creating a tentative file first locates the largest empty 
file available and creates a tentative file in that space. 
This insures the maximum space into which the file can expand. 
The user program then writes data into the tentative file. 
At the end of the data, the program calls the USR to close 
the tentative file, making it a permanent file. The USR 
does so and allocates whatever space remains on the end of 
the tentative file to a new, smaller, empty file. 

1.2.4 File Directories and Additional Information Words 

To maintain records of the files on a device, PS/8 allocates 
blocks 1 through 6 of each file structured device as the file 
directory. Entries in this directory inform the system of 
the name, size, and location of each file, including all empty 
files and the tentative file, if one exists. For a detailed 
description of the entries in the file directory J see Appendix 
A. 

Each entry in a directory can, optionally, have extra storage 
words called Additional Information Words. The number of 
Additional Information Words is determined at the time the 
directory is intially created (normally by using the /S or 
/Z features of PIP; see Chapter 6 in the 8K Programming System 
User's Guide. 
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Whenever Additional Information Words are used, the first one 
for each file entry is used to store the value of the System 
Date Word at the time the file was created. This value is 
set by executing a DATE conmiand (see Chapter 2 in the 
8K Programming System User's Guide ) . 



NOTE 



The value of the system DATE word is contained in 
location 7666 in field 1; this word has the follow- 
ing format: 



34 8 9 11 



MONTH DAY YEAR- 19 70 
(l-14g) (l-37g) (0-7) 

A date word of implies that no DATE command has been executed 
since the system intialization. 

The values of Additional Information Words beyond the first 
are user-defined. See Appendix D for further information on 
Additional Information Words. 

1.3 Core Control Block 

Associated with each core image file (.SV file) is a block of 
data called the Core Control Block. The Core Control Block 
is a table of information containing the program's starting 
address, areas of core into which the program is loaded, and 
the program's Job Status Word. The Core Control Block is 
created at the time the program is loaded by the ABSLDR or 
LOADER program and is written onto the . SV file by the SAVE 
operation. More information on the Core Control Block can be 
found in the description of core image files in section A. 2. 2. 
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NOTE 



Specifying arguments to the SAVE command as described 
in the 8K t>rogramming System User's Guide can alter 
the contents of that program's Core Control Block. 



When a program is loaded the starting address and Job Status 
Word are loaded from the Core Control Block and saved in 
core. The Core Control Block itself is saved in one of the 
system scratch blocks unless the program was loaded with the 
R (rather than GET or RUN) command. 

1.3.1 Program Starting Address 

The current starting address (used by the START command) is 
stored in two words at locations 7744 and 7745 in field 0. 
The format of these words is: 



NOTES 

N is the field in which 
to start 

Starting address of the 
program 



1.3.2 Job Status Word 

The Job Status Word contains certain flags that affect PS/S 
operations, such as whether to save core when loading the 
USR or Command Decoder. The Job Status Word for the program 
currently in core is saved at location 7746 in field and 
contains the following information: 

Bit Condition Meaning 

Bit J? = 1 File does not load into locations 

to 1777 in field 0. 

Bit 1=1 File does not load into locations 

to 1777 in field 1. 

Bit 2=1 Program must be reloaded before it 

can be restarted. 
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LOCATION 


CONTENTS 


7744 


62N3 


7745 


addr 



Bit Condition Meaning 

Bits 3-9 Reserved for future use. 

Bit 1^ = 1 Locations to 1777 in field 

need not be saved when calling 
the Command Decoder. 

Bit 11 = 1 Locations to 1777 in field 1 

need not be saved when calling 
the USR. 

More information on the Core Control Block can be found in 
the description of Core Image (.SV) files found in Appendix A. 

NOTE 

When bit 2 is 1, any attempt to perform a 
START (without an explicit address) results 
in a 

NO! ! 

error message being printed. As this bit is 
always zero in the Core Control Block, the 
user program is expected to internally set 
this bit (in location 7746) if a program is 
not restartable. This could be done as fol- 
lows : 

CDF 

TAD 7746 /LOAD JOB STATUS WORD 

AND (6777 

TAD (.1000 

DCA 7746 /JOB IS NOT RESTARTABLE 

1.4 Device Names and Device Numbers 

The PS/8 system can accommodate up to 15 separate devices. 
In the 8K Programming System User's Guide the reader is intro- 
duced to the concept of device names. Briefly, each device on 
the system is recognized by either a permanent device name 
(such as PTR or DTAl) which is created when the system is 
built, or a user-defined device name determined by an ASSIGN 
command. The system insures that the user-defined device 
name takes precedence. For example, 

.ASSIGN DSK DTA4 
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causes all future references to DTA4 to address the device DSK. 

In calling the User Service Routine, a device can be alter- 
natively recognized by a device number. Each device on the 
system has a unique predefined number in the range 1 to 15 (17 g) 
assigned at the time the system is generated. 

Thus, user programs have the choice of referring to a device 
by either name or number. Referencing a device by name is 
preferable as it maintains device independence for the program. 

1.5 The DEVICE and FILENAME Pseudo-ops 

Several of the User Service Routine functions take device 
names or file names as arguments. To simplify the task of 
generating these arguments, the DEVICE and FILENAME pseudo-ops 
have been added to the PALS Assembler. 

A device name consists of a two word block, containing four 
alphanumeric characters in six-bit ASCII format. A block in 
this format can be created by the DEVICE pseudo-op as follows: 

DEVICE DTAl 
generates the following two words: 

0424 
J2fl61 

Similarly, the FILENAME pseudo-op creates a four word block, 
the first three words of which contain the file name and the 
fourth word of which contains the file extension. For example: 

FILENAME PIP.SV 
generates the following four words : 
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2^11 
2000 
0000 
2326 



Note that positions for characters 4 through 6 are filled with 
zeros . 

The DEVICE and FILENAME pseudo-ops are used in examples in the 
following chapters. 
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CHAPTER 2 



User Service Routine 



The User Service Routine, or USR, is a collection of sub- 
routines which perform the operations of opening and closing 
files, loading device handlers, chaining programs together, 
and calling the Command Decoder. It provides these functions 
not only for the system itself, but for all programs running 
under the PS/ 8 system. 

2.1 Calling the USR 

Performing any USR function is as simple as giving a JMS 
followed by the proper arguments. Calls to the USR take a 
standardized calling sequence. This standard call should be 
studied before progressing to the operation of the various USR 
functions . 

2.1.1 Standard USR Call 

In the remainder of this chapter, the following calling 
sequence is referenced: 



TAD VAL The contents of the AC is applicable in 

some cases only. 
CDF N Where N is the value of the current pro- 
gram field multiplied by 10 octal. 
CIF 10 
JMS I (USR Where USR is either 7700 or 0200, see 

section 2.1.2) . 
FUNCTION This word contains an integer from 1 to 

13 octal indicating which USR operation 

is to be performed. 
ARG(l) The number and meaning of these argument 
'. words varies with the particular USR 

function to be performed, 
error return When applicable, this is the return 

address for all errors, 
normal return 
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This calling sequence can change from function to function. 
For example, some functions take no value in the AC and others 
have fewer or greater numbers of arguments. Nonetheless, this 
format is generally followed. 

NOTE 

The CDF and GIF instructions preceding the JMS 
to the USR in the calling sequence are very im- 
portant. The DATA FIELD must be set to the cur- 
rent field and the INSTRUCTION FIELD must be set 
to 1 when calling the USR. In the examples given 
in this chapter, it is arbitrarily assumed that 
the call to the USR is made from field 0. On 
return from any USR function the DATA FIELD re- 
mains set to the current field and the AC is zero. 

There are three other restrictions which apply to all USR 
calls, as follows: 

a. The USR can never be called from any address between 
10000 and 11777*. Attempting to do so results in 
the printing of the : 

MONITOR ERROR 4 AT xxxxx 

message and termination of program execution. The 
value of xxxxx is the address of the calling se- 
quence (in all such MOIIITOR ERROR messages) . 

b. Several USR calls take address pointers as arguments. 
These pointers always refer to data in the same field 
as the call. 

c. When calling the USR from field 1, these address 
pointers must never refer to data that lies in the 
area 10000 to 11777. 



2.1.2 Direct and Indirect Calling Sequence 

A user program can call the USR in two ways. First, by per- 
forming a JMS to location 17700 (location 7700 in field 1) , ad- 
dresses in field 1 are written in this format). In this case. 



*Where five digit addresses are given the leading digit refers 
to the field. Thus, 11777 is location 1777 in field 1. 
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locations 10000 to 11777 are saved on a special area on the 
system device, and the USR is then loaded into 10000 to 11777. 
When the USR operation is completed, locations 10000 to 11777 
are restored to their previous values. 

NOTE 

By setting bit 11 of the Job Status Word to 
a 1, the user can avoid this saving and re- 
storing of core when preserving core is un- 
necessary. 

Alternatively, a program can opt to keep the USR permanently 
resident in core at locations 10000 to 11777 by using the USRIN 
function (see section 2.2.8). Once the USR has been brought into 
core, a USR call can be made by performing a JMS to location 10200, 
This is a more efficient way of calling the USR. When USR opera- 
tions have been completed, the program restores locations 10000 
to 11777 to their initial state by executing the USROUT function 
(see section 2.2.9). 

2.2 Summary of USR Functions 

Function 

Code Name Operation 

1 FETCH Load a device handler into core. Returns 

entry address of the handler. 

2 LOOKUP* Searches the file directory on any device 

to locate a specified permanent file. 

3 ENTER* Creates and opens for output a tentative 

file on a specified device. 

4 CLOSE* The currently open tentative file on the 

specified device is closed and becomes a 
permanent file. Also, any previous per- 
manent file with the same name is deleted. 



*If the specified device is not file structured, the LOOKUP, ENTER, 
and CLOSE functions verify only that the device is acceptable for 
input in the case of LOOKUP, or output in the case of ENTER or CLOSE. 
For example, ENTERing a file on the paper tape punch is a legal func- 
tion. 
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Function 

Code Name 

5 DECODE 



CHAIN 



10 



11 



ERROR 



USRIN 



US ROUT 



12 INQUIRE 



13 RESET 



14-17 



Operation 

The Command Decoder is called. The function 
of the Command Decoder is described in Chap- 
ter 3. 

Loads a specified core image file from the 
system device and starts it. 

Prints an error message of the form 
USER ERROR n AT LOCATION xxxxx 

The USR is loaded into core. Subsequent 
calls to the USR are by a JMS to 10200. 

Dismisses the USR from core and restores 
the previous contents of locations 10000 
to 11777. 

Ascertains whether a given device exists 
and, if so, whether its handler is in core. 

Resets system tables to their initial cleared 
state. 

Not currently used, these request numbers 
are reserved for future use. 



2.2.1 FETCH Device Handler 



Function Code = 1 



Device handlers must be loaded into core so as to be avail- 
able to the USR and user program for I/O operations on that de- 
vice. Before performing a LOOKUP, ENTER, or CLOSE function on 
any device, the handler for that device must be loaded by FETCH, 

The FETCH function takes two distinct foirms : 



a. Load a device handler corresponding to a given 
device name , and 

b. Load a device handler corresponding to a given 
device number. 
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CLA 




CDF 





GIF 


10 


JMS 


I (USR 


1 




DEVICE DTA3 


6i2f|2(l 


JMP 


ERR 



First, the following is an example of loading a handler 
by name: 



/AC MUST BE CLEAR 



/FUNCTION CODE = 1 
/GENERATES TWO WORDS: ARG(l) 
/AND ARG(2) 
/ARG ( 3 ) 
/ERROR RETURN 
/NORMAL RETURN 



ARG(l) and ARG (2) contain the device name in standard format. 
If the normal return is taken, ARG (2) is changed to the device 
number corresponding to the device loaded. ARG(3) contains the 
following information: 

Bits to 4 contain the page number into which the 
handler is loaded. 

Bit 11 is if the user program can only accept a 
one page handler. 

Bit 11 is 1 if there is room for a two page handler. 

Notice that in the example above, the handler for DTA3 is to be 
loaded into locations 60 00 to 6177. If necessary, a two page 
handler could be loaded; the second page would be placed in 
locations 62 00 to 6377. After a normal return, ARG (3) is changed 
to contain the entry point of the handler. 

A different set of arguments is used to fetch a device 
handler by number . The following is an example of this form: 

TAD VAL /AC IS NOT ZERO 

CDF 

CIF 10 

JMS I (USR 

1 /FUNCTION CODE = 1 

60)31 /ARG(l) 

JMP ERR /ERROR RETURN 

: /NORMAL RETURN 
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On entry to the USR the AC contains the device number in bits 
8 to 11 (bits to 7 are ignored) . 

The format for ARG(l) is the same as that for ARG(3) in the 
previous example. Following a normal return ARG(l) is replaced 
with the entry point of the handler. 

The conditions that can cause an error return to occur in 
both cases are as follows : 



a. There is no device corresponding to the given 
device name or device number, or 

b. An attempt was made to load a two page handler 
into one page. If this is an attempt to load 
the handler by name, the contents of ARG(2) 
have been changed already to the internal de- 
vice number. 



In addition, one of the following Monitor errors can be 
printed, followed by a return to the Keyboard Monitor: 



Error Message 
MONITOR ERROR 4 AT xxxxx 

MONITOR ERROR 5 AT xxxxx 



Meaning 

Results if bits 8 to 11 of the 
AC are zero (and bits to 7 are 
non-zero) . 

Results if a read error occurs 
while loading the device handler. 



The FETCH function checks to see if the handler is in core, 
and if it is not, then the handler and all co-resident* handlers 
are loaded. While the FETCH operation is essentially a simple 
one, the user should be aware of the following points: 

a. Device handlers are always loaded into field 0. 



*Two or more device handlers are "co-resident" when they are both 
included in the same one or two core pages. For example, the 
paper tape reader and punch routines are co-resident, as are the 
eight DECtape handler routines. 
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b. The entry point that is returned may not be on 

the page desired. This would happen if the handler 
were already resident. 

c. Never attempt to load a handler into 7600 or into 
page 0. Never load a two page handler into 7400. 

For more information on using device handlers, see Chapter 4. 

2.2.2 LOOKUP Permanent File Function Code = 2 

This request locates a permanent file entry on a given 

device, if one exists. An example of a typical LOOKUP would be: 

TAD VAL /LOAD DEVICE NUMBER 
CDF 
CIF 10 
JMS I (USR 

2 /FUNCTION CODE = 2 

NAME /ARG(l) , POINTS TO FILE NAME 

/ARG(2) 

JMP ERR /ERROR RETURN 

/NORMAL RETURN 

NAME, FILENAME PROG. PA 

This request looks up a permanent file entry with the name PROG. PA. 
The device number on which the lookup is to be performed is in AC 
bits 8 to 11. ARG(l) contains a pointer to the file name; note 
that the file name block must be in the same field as the call, 
and that it cannot be in locations 10000 to 11777. The device 
handler must have been previously loaded into core. If the nor- 
mal return is taken, ARG(l) is changed to the starting block of 
the file and ARG(2) contains the file length in blocks as a nega- 
tive number. If the device specified is a readable, non-file 
structured device (for example, the paper tape reader), then ARG(l) 
and ARG(2) are both set to zero. 

If the error return is taken, ARG(l) and ARG(2) are unchanged. 
The following conditions cause an error return: 
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a. The device specified is a write-only device. 

b. The file specified was not found. 

In addition, specifying illegal arguments can cause one of the 
following monitor errors, followed by a return to the Keyboard 
Monitor: 



Error Message 



MONITOR ERROR 2 AT XXXXX 



MONITOR ERROR 3 AT xxxxx 



MONITOR ERROR 4 AT xxxxx 



Meaning 

Results if an I/O error 
occurred while reading the 
device directory. 

Results if the device handler 
for the specified device is 
not in core . 

Results if bits 8 to 11 of 
the AC are zero. 



The LOOKUP function is the standard method of opening a perma- 
nent file for input. 



2.2.3 ENTER Output (Tentative) File 



Function Code = 3 



The ENTER function is used to create a tentative file entry to 
be used for output. An example of a typical ENTER function is 
as follows: 



TAD VAL 

CDF fi 

GIF Ij? 

JMS I (USR 
3 
NAME 

JMP ERROR 



NAME, FILENAME PROG.LS 



/AC IS NOT ZERO 



/FUNCTION CODE = 3 

/ARG(l) POINTS TO FILE NAME 

/ARG(2) 

/ERROR RETURN 

/NORMAL RETURN 



Bits 8 to 11 of the AC contain the device number of the selected 
device; the device handler for this device must be loaded into 
core before performing an ENTER function. If bits to 7 of the 
AC are non-zero, this value is considered to be a declaration of 
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the maximum length of the file. The ENTER function searches 
the file directory for the smallest empty file that contains at 
least the declared number of blocks. If bits to 7 of the AC 
are zero, the ENTER function locates the largest available empty 
file. 

On a normal return, the contents of ARG(l) are replaced with the 
starting block of the file. The 2's complement of the actual 
length of the created tentative file in blocks (which can be 
equal to or greater than the requested length) replaces ARG{2) . 
If the file directory contains any Additional Information Words, 
the system DATE (location 17666) is written as the first Additional 
Information Word of the newly created tentative file at this time. 



NOTE 

If the selected device is not file structured 
but permits output operations (e.g., the high 
speed punch) , the ENTER operation always suc- 
ceeds. In this case, ARG(l) and ARG(2) are 
both zeroed on return. 



If the error return is taken, ARG(l) and ARG(2) are unchanged. 
The following conditions cause an error return: 



a. The device specified by bits 8 to 11 of the AC 
is a read only device. 

b. No empty file exists which satisfies the requested 
length requirement. 

c. Another tentative file is already active on this 
device (only one output file can be active at 
any given time) . 

d. The first word of the file name was (an illegal 
file name) . 



In addition, one of the following monitor errors can occur, 
followed by a return to the Keyboard Monitor: 
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Error Message 
MONITOR ERROR 2 AT xxxxx 

MONITOR ERROR 3 AT xxxxx 

MONITOR ERROR 4 AT xxxxx 
MONITOR ERROR 5 AT xxxxx 

MONITOR ERROR 6 AT xxxxx 



Meaning 

Results if an I/O error occurred 
while reading or writing the de- 
vice directory. 

Results if the device handler for 
the specified device is not in 
core . 

Results if AC bits 8 to 11 are 
zero. 

Read error on the system device 
while bringing in the overlay 
code for the ENTER function. 

Results if a directory overflow 
occurred (no room for tentative 
file entry in directory) . 



2.2.4 The CLOSE Function 



Function Code = 4 



The CLOSE function has a dual purpose: first, it is used to 
close the current active tentative file, making it a permanent 
file- Second, when a tentative file becomes permanent it is 
necessary to remove any permanent file having the same name; 
this operation is also performed by the CLOSE function. An 
example of CLOSE usage follows : 



TAD 


VAL 


/GET DEVICE NU] 


CDF 







CIF 


10 




JMS 


I (USR 




4 
NAMI 


li 


/FUNCTION CODE 
/ARG(l) 


15 




/ARG(2) 


JMP 


ERR 


/ERROR RETURN 


• 




/NORMAL RETURN 



= 4 



NAME, FILENAME PROG.LS 

The device number is contained in AC bits 8 to 11 when calling 
the USR. ARG(l) is a pointer to the name of the file to be de- 
leted and ARG(2) contains the number of blocks to be used for 
the new permanent file. 
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The normal sequence of operations on an output file is: 



a. FETCH the device handler for the output device. 

b. ENTER the tentative file on the output device, 
getting the starting block and the maximum 
number of blocks available for the file. 

c. Perform the actual output, using the device 
handler, keeping track of how many blocks are 
written, and checking to insure that the file 
does not exceed the available space. 

d. CLOSE the tentative file, making it permanent. 
The CLOSE operation would always use the same 
file name as the ENTER performed in step b. 
The closing file length would have been com- 
puted in step 



After a normal return from CLOSE, the active tentative file is 
permanent and any permanent file having the specified file name 
already stored on the device is deleted . If the specified de- 
vice is a non-file structured device that permits output (the 
paper tape punch, for example) , the CLOSE function will always 
succeed. 



NOTE 

The user must be careful to specify 
the same file names to the ENTER and 
the CLOSE functions. Failure to do 
so can cause several permanent files 
with identical names to appear in the 
directory. If CLOSE is intended only 
to be used to delete some existing 
file, then the number of blocks, ARC (2) 
should be zero. 



The following conditions cause the error return to be taken: 



a. The device specified by bits 8 to 11 of the 
AC is a read only device. 

b. There is neither an active tentative file to 
be made into a permanent file, nor a permanent 
file with the specified name to be deleted. 
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In addition, one of the following Monitor errors can occur: 

Error Message Meaning 

MONITOR ERROR 1 AT xxxxx Results if the length specified 

by ARG(2) exceeded the allotted 
space. 

MONITOR ERROR 2 AT xxxxx Results if an I/O error occurred 

while reading or writing the de- 
vice directory. 

MONITOR ERROR 3 AT xxxxx Results if the device handler for 

the specified device is not in core. 

MONITOR ERROR 4 AT xxxxx Results if AC bits 8 to 11 are zero. 

2.2.5 Call Command Decoder (DECODE) Function Code = 5 

The DECODE function causes the USR to load and execute the Com- 
mand Decoder. The Command Decoder accepts (from the Teletype) 
a list of input and output devices and files, along with various 
options. The Command Decoder performs a LOOKUP on all input 
files, sets up necessary tables in the top page of field 1, and 
returns to the user program. These operations are described in 
detail in Chapter 3, which should be read before attempting to 
use the DECODE function. 

A typical call to the Command Decoder looks as follows: 

CDF 

CIF 10 

JMS I (USR 

5 /FUNCTION CODE = 5 

2001 /ARG(l) , ASSUMED INPUT EXTENSION 

/ARGC2), ZERO TO PRESERVE ALL 

/TENTATIVE FILES 

/NORMAL RETURN 



ARG(l) is the assumed input extension, in the above example 
it is ".PA". on return from the Command Decoder, information 
is stored in tables located in the top page of field 1. The 
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DECODE function also resets all system tables as in the RESET 
function (see RESET function, section 2.2.11) if ARG(2) is 
all currently active tentative files remain open; if ARG(2) 
is non-zero all tentative files are deleted and the normal 
return is to ARG(2) instead of ARG(2)+1. 

The DECODE function has no error return (Command Decoder error 
messages are given in Chapter 3) . However, the following Monitor 
error can occur: 

Error Message Meaning 

MONITOR ERROR 5 AT xxxxx I/O error occurred while reading 

or writing on the system device. 

2.2.6 CHAIN Function Function Code = 6 

The CHAIN function permits a program to load and start another 
program with the restriction that the program chained to must 
be a core image (.SV) file located on the system device. A 
typical implementation of the CHAIN function looks as follows: 

CDF 

CIF 10 

JMS I (USR 

6 /FUNCTION CODE = 6 

BLOCK /ARG(l), STARTING BLOCK NUMBER 

There is no normal or error return from CHAIN. However, the 
following monitor error can occur: 

Error Message Meaning 

MONITOR ERROR 5 AT XXXXX I/O error occurred while reading 

or writing on the system device. 

The CHAIN function loads a core image file located on the system 
device beginning at the block number specified as ARG(l) (which 
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is normally determined by performing a LOOKUP on the desired 
file name) . Once loaded, the program is started at an address 
one greater than the starting address specified by the program's 
Core Control Block. 

CHAIN automatically performs a USROUT function (see section 
2.2.9) to dismiss the USR from core, and a RESET to clear all 
system tables (see section 2.2.11), but CHAIN does not delete 
tentative files. 

The areas of core altered by the CHAIN function are determined 
by the contents of the Core Control Block of the core image 
file loaded by CHAIN. The Core Control Block for the file is 
set up by the ABSLDR or LOADER programs. It can be modified 
by performing a SAVE command with specific arguments. Every 
page of core in which at least one location was saved is loaded. 
If the page is one of the "odd numbered" pages (pages 1, 3, etc. ; 
locations 0200 to 0377, 0600 to 0777, etc.), the previous page 
is always loaded. In addition, CHAIN always alters the contents 
of locations 07200 to 07577. 

NOTE 

CHAIN destroys a necessary part of the ODT resi- 
dent breakpoint routine. Thus an ODT breakpoint 
should never be maintained across a CHAIN. 

With the above exceptions, programs can pass data back and forth 
in core while chaining. For example, FORTRAN programs normally 
leave the COMMON area in field 1 unchanged. This COMMON area 
can then be accessed by the program activated by the CHAIN. 

2.2.7 Signal User ERROR Function Code = 7 

The USR can be called to print a user error message for a pro- 
gram. The following is a possible ERROR call: 

CDF 

CIF IjS 

JMS I CUSR 

7 /FUNCTION CODE = 7 

2 /ARG(l) , ERROR NUMBER 
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The ERROR function causes a message of the form: 

USER ERROR n AT xxxxx 

to be printed. Here n is the error number given as ARG(l) ; 
n must be between and Up/ and xxxxx is the address of ARG(l). 
If ARG(l) in the sample call above was at location 500 in field 0, 
the message: 

USER ERROR 2 AT 00500 

would be printed. Following the message, the USR returns con- 
trol to the Keyboard Monitor, preserving the user program in- 
tact. 

The error number is arbitrary. Two numbers have currently as- 
signed meanings : 

Error Message Meaning 

USER ERROR AT xxxxx During a RUN, GET, or R command, 

this error message indicates that 
an error occurred while loading 
the core image. 

USER ERROR 1 AT xxxxx While executing a FORTRAN or SABR 

program, this error indicates that 
a call was made to a subroutine 
that was not loaded. 

2.2.8 Lock USR in Core (USRIN) Function Code = 10 

When making a number of calls to the USR it is advantageous for 
a program to avoid reloading the USR each time a USR call is 
made. The USR can be brought into core and kept there for sub- 
sequent use by the USRIN function. The calling sequence for the 
USRIN function looks as follows: 

CDF 

GIF 10 

JMS I (77|2fj3 

10 /FUNCTION CODE = 10 

I /NORMAL RETURN 
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The USRIN function saves the contents of locations 10000 to 
11777 on the system scratch blocks, loads the USR into this 
area in core, and returns control to the user program. 



NOTE 

If bit 11 of the current Job Status Word is a one, 
the USRIN function will not save the contents of 
locations 10000 to 11777. 



Subsequent calls to the USR can be made directly by performing 
a JMS to location 02 00 in field 1, saving the time necessary 
to reload the USR each time it is called. 

2.2.9 Dismiss USR from Core (USROUT) Function Code = 11 

When a program has loaded the USR into core with the USRIN 
function and no longer wants or needs the USR in core, the 
USROUT function is used to restore the original contents of 
locations 10000 to 11777. The calling sequence for the USROUT 
function is as follows : 



CDF 

GIF 10 

JMS I {200 /DO NOT JMS TO 11100 M 

11 /FUNCTION CODE = 11 

: /NORMAL RETURN 



The USROUT function and the USRIN function are complementary 
operations. Subsequent calls to the USR must be made by per- 
forming a JMS to location 7700 in field 1. 



NOTE 

If bit 11 of the current Job Status Word is a 
1, the contents of core are not changed by the 
USROUT function. In this case USROUT is a re- 
dundant operation since core was not preserved 
by the USRIN function. 
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2.2.10 Ascertain Device Information (INQUIRE) Function Code = 12 

On some occasions a user may wish to determine what internal 
device number corresponds to a given device name or whether the 
device handler for a specified device is in core, without ac- 
tually performing a FETCH operation. INQUIRE performs these 
operations for the user. The function call for INQUIRE closely 
resembles the FETCH handler call. 

INQUIRE, like FETCH, has two distinct forms: 

a. Obtain the device number corresponding to a 
given device name and determine if the handler 
for that device is in core (example shown below) , 
and 

b. Determine if the handler corresponding to a 
given device number is in core. 

An example of the INQUIRE call is shown below: 

/AC MUST BE CLEAR 



/FUNCTION CODE = 12 
/GENERATES TWO WORDS 
/ARG(l) AND ARG(2) 
/ARG(3) 
/ERROR RETURN 
/NORMAL RETURN 



ARG(l) and ARG(2) contain the device name in standard format. 
When the normal return is taken ARG(2) is changed to the device 
number corresponding to the given name, and ARG(3) contains 
either the entry point of the device handler if it is already 
in core, or zero if the corresponding device handler has not yet 
been loaded. 



CLA 




CDF 





CIF 


10 


JMS 


I (USR 


12 




DEVICE DTA3 







JMP 


ERR 
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A slightly different set of arguments is used to inquire 
about a device by its device number: 



TAD VAL /AC IS NON-ZERO 

CDF 

CIF lj2f 

JMS I (USR 

12 /FUNCTION CODE =12 



/ARG(l) 

JMP ERR /ERROR RETURN 

: /NORMAL RETURN 



On entry to INQUIRE, AC bits 8 to 11 contain the device 
number (bits to 7 are ignored) . 



NOTE 

If AC bits to 7 are non-zero, and bits 8 
to 11 are zero (an illegal device number) a: 

MONITOR ERROR 4 AT xxxxx 

message is printed and program execution is 
terminated. 



On normal return ARG(l) is set to the entry point of the device 
handler if it is already in core, or zero if the corresponding 
device handler has not yet been loaded. 

The error return in both cases is taken only if there is no 
device corresponding to the device name or number specified. 

2.2.11 RESET System Tables Function Code = 13 

There are certain occasions when it is desired to reset the 
system tables, effectively removing from core all device 
handlers except the system handler. An example of the RESET 
function is shown below: 
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CDF 

CIF 10 

JMS I (USR 

13 /FUNCTION CODE = 13 

/0 PRESERVES TENTATIVE FILES 

: /NORMAL RETURN 

RESET zeros all entries except the one for the system device in 
the Device Handler Residency Table (see section B.3.3), removing 
all device handlers, other than that for the system device, from 
core. This should be done anytime a user program modifies any 
page in which a device handler was loaded. 

RESET has the additional function of deleting all currently ac- 
tive tentative files (files that have been entered but not closed) 
This is accomplished by zeroing bits 9 through 11 of every entry 
in the Device Control Word Table (see section B.3.5). 

If RESET is to be used in this last fashion, to delete all active 
tentative files, then ARG(l) must be non-zero and the normal re- 
turn is to ARG(l) rather than to ARG(1)+1. For example, the fol- 
lowing call would serve this purpose: 

CDF 

CIF 10 

JMS I (USR 

13 /FUNCTION CODE =13 

CLA CMA /NON-ZERO! 

The normal return would execute the CLA CMA and all active 
tentative files on all devices would be deleted. 
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CHAPTER 3 



THE COMMAND DECODER 



PS/8 provides a powerful subroutine called the Comniand Decoder 
for use by all system programs. The Command Decoder is norm- 
ally called when a program starts running. When called, the 
Command Decoder prints a * and then accepts a command line from 
the console Teletype that includes a list of I/O devices, file 
names, and various option specifications. The Command Decoder 
validates the command line for accuracy, performs a LOOKUP on 
all input files, and sets up various tables for the calling 
program. 

The operations performed by the Command Decoder greatly simplify 
the initialization routines of all PS/8 programs. Also, since 
command lines all have a standard basic structure, the Command 
Decoder makes learning to use PS/8 much simpler. 

3 . 1 Command Decoder Conventions 

Chapter 3 in the 8K Programming System User's Guide describes 
the syntax for the command line in detail. A brief synopsis 
is given here only to clarify the later discussion in this 
chapter. 

The command line has the following general form: 

* output files < input files (options) 

There can be to 3 output files and to 9 input files speci- 
fied. 

Output File Format Meaning 

EXPLE.EX Output to a file named EXPLE.EX on 

device DSK (the default file storage 
device) . 
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Output File Forma t 
LPT: 

DTA2:EXPLE.EX 

DTA2:EXPLE.EX[99] 

null 



Meaning 

Output to the LPT. This format generally 
specifies a non-file structured device. 

Output to a file named EXPLE.EX on device 
DTA2. 

Output to a file named EXPLE.EX on device 
DTA2. A maximum output file size of 99 
blocks is specified. 

No output specified. 



An input file specification has one of the following forms :: 
Input File Format Meaning 



DTA2 : INPUT 



DTA2: INPUT. EX 



INPUT. EX 



Input from a file named INPUT. df on de- 
vice DTA2. "df" is the assumed input 
file extension specified in the Command 
Decoder. * 

Input from a file named INPUT. EX on device 
DTA2. In this case .EX overrides the as- 
sumed input file extension. 

Input from a file named INPUT. EX. If 
there is no previously specified input 
device, input is from device DSK, the 
default file storage device; otherwise, 
the input device is the same as the last 
specified input device. 

Input from device PTR; no file name is 
needed for non-file structured devices. 

Input from device DTA2 treated as a 
non-file structured device, as, for 
example, in the PIP command line: 

*TTY : /L < DTA2 : 

*Whe never a file extension is left off an input file specifica- 
tion, the Command Decoder first performs a LOOKUP for the given 
name appending a specified assumed extension. If that LOOKUP 
fails, a second LOOKUP is made for the file appending a null 
(zero) extension. 



PTR: 



DTA2 
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Input File Format Meaning 

In both of the last two formats, no 
LOOKUP operation is performed since the 
device is assumed to be non-file struc- 
tured. 

null Repeats input from the previous device 

specified (must not be first in input 
list, and must refer to a non-file 
structured device). For example: 

* < PTR: , , 

(two null files) indicates that three 
paper tapes are to be loaded. 

The Command Decoder verifies that the specified device names, 
file names, and extensions consist only of the characters A 
through Z and through 9. If not, a syntax error is generated 
and the command line is considered to be invalid. 

There are two kinds of options that can be specified: first, 
alphanumeric option switches are denoted by a single alphanumeric 
character preceded by a slash (/) or a string of characters en- 
closed in parentheses; secondly, a numeric option can be speci- 
fied as an octal number from 1 to 3 77 77 77 7 preceded by an equal 
sign (=) . These options are passed to the user program and 
are interpreted differently by each program. 

Finally, the Command Decoder permits the command line to be 
terminated by either the RETURN or ALT MODE key. This informa- 
tion is also passed to the user program. 

3.2 Command Decoder Error Messages 

If an error in the command line is detected by the Command De- 
coder, one of the following error messages is printed. After 
the error message, the Command Decoder starts a new line, 
prints a *, and waits for another command line. The erroneous 
command is ignored. 
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E rror Message Meaning 

ILLEGAL SYNTAX The coirmand line is formatted incor- 
rectly. 

TOO MANY FILES More than three output files or nine 

input files were specified. 

device DOES NOT EXIST The specified device name does not 

correspond to any permanent device 
name or any user assigned device name. 

name NOT FOUND The specified input file name was not 

found on the selected device. 



3.3 Calling the Command Decoder 

The Command Decoder is initiated by the DECODE function of the 
USR. DECODE causes the contents of locations to 1777 of 
field to be saved on the system scratch blocks, and the Com- 
mand Decoder to be brought into that area of core and started. 
When the command line has been entered and properly interpreted, 
the Command Decoder exits to the USR, which restores the original 
contents of to 1777 and returns to the calling program. 



NOTE 

By setting bit 10 of the Job Status Word to a 1 
the user can avoid this saving and restoring of 
core for programs that do not occupy locations 
to 1777. 



The DECODE call can reside in the area between and 1777 in 
field and still function correctly. A typical call would 
appear as follows : 

CDF /SET DATA FIELD TO CURRENT FIELD 

CIF lj3 /INSTRUCTION FIELD MUST BE 1 

JMS I (USR /\5SR=n00 IF USR IS NOT IN CORE 

/OR USR=J2f2j2(0 IF USRIN WAS PERFORMED 
5 /DECODE FUNCTION = 5 

2j2fj2fl /ARG(l) , ASSUMED INPUT EXTENSION 

/ARG(2), ZERO TO PRESERVE 

/ALL TENTATIVE FILES 
: /NORMAL RETURN 
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ARG(l) is the assumed input extension. If an input file name 
is given with no specified extension, the Command Decoder 
first performs a LOOKUP for a file having the given name with 
the assumed extension. If the LOOKUP fails, the Command De- 
coder performs a second LOOKUP for a file having the given name 
and a null (zero) extension. In this example, the assumed input 
extension is ".PA". 

DECODE performs an automatic RESET operation (see section 2.2.11) 
to remove from core all device handlers except those equivalent 
to the system device. As in the RESET function, if ARC (2) is 
zero all currently active tentative files are preserved. If 
ARC (2) is non-zero, all tentative files are deleted and DECODE 
returns to ARC (2) instead of ARG(2)+1. 

As the Command Decoder normally handles all of its own errors, 
there is no error return from the DECODE operation. 

3.4 Command Decoder Tables 

The Command decoder sets up various tables in the top page of 
field 1 that describe the command line typed to the user program. 

3.4.1 Output Files 

There is room for three entries in the output file table that 
begins at location 1760i2(. Each entry is five words long and 
has the following format: 



1 23456789 10 11 



WORD 1 
WORD 2 
WORD 3 
WORD 4 
WORD 5 



USER SPECIFIED 
FILE LENGTH 


4-BIT DEVICE 
NUMBER 


FILE NAME 
CHARACTER 1 


FILE NAME 
CHARACTER 2 


FILE NAME 
CHARACTER 3 


FILE NAME 
CHARACTER 4 


FILE NAME 
CHARACTER 5 


FILE NAME 
CHARACTER 6 


FILE EXTENSION 
CHARACTER 1 


FILE EXTENSION 
CHARACTER 2 



OUTPUT FILE NAME 
6 CHARACTERS 



FILE EXTENSION 
2 CHARACTERS 
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Bits to 7 of word 1 in each entry contain the file length, 
if the file length was specified with the square bracket con- 
struction in the command line. Otherwise, those bits are zero. 

The entry for the first output file is in locations 17600 to 
17604, the second is in locations 17605 to 17611, and the 
third is in locations 17612 to 17616. If word 1 of any entry 
is zero, the corresponding output file was not specified. A 
zero in word 2 means that no file name was specified. 

Also, if word 5 of any entry is zero no file extension was 
specified for the corresponding file. It is left to the user 
program to take the proper action in these cases. 

These entries are in a format that is acceptable to the ENTER 
function. 

3.4.2 Input Files 

There is room for nine entries in the input file table that 
begins at location 17 617. Each entry is two words long and 
has the following format: 



WORD i 



WORD 2 



12 3 4 5 6 7 


8 9 10 11 


MINUS FILE 
LENGTH 


4-BIT DEVICE 
NUMBER 


STARTING BLOCK OF FILE 



Bits to 7 of word 1 contain the file length as a negative 
number. Thus, 377p. in these bits is a length of one block, 376 
is a legnth of two blocks, etc. If bits to 7 are zero, the 
specified file has a length greater than or equal to 256 blocks 
or a non-^file structured device was specified. 
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This restri 
fied size c 
gram has no 
tions. For 
mode any fi 
is greater 
can handle 
files of un 
will detect 



NOTE 

ction to 255 blocks of actual speci- 
an cause some problems if the pro- 
way of detecting end-of-file condi- 
example, PIP cannot copy in image 
le on a file structured device that 
than 255 blocks long, although it 
in /A or /B modes (ASCII or Binary) 
limited size. In /A or /B modes PIP 
the CTRL/Z marking the end-of-file. 



If this is liable to be a problem, it is sug- 
gested that the user program employ the special 
mode of the Command Decoder described in section 
3.5 and perform its own LOOKUP on the input files 
to obtain the exact file length. 



The two word input tables begin in locations 17617, 17621, 17623, 
17625, 17627, 17631, 17633, 17635, and 17637. If location 17617 
is zero no input files were indicated in the command line. If 
less than nine input files were specified, the unused entries 
in the input file list are zeroed (location 17641 is always set 
to provide a zero terminator even when nine files are specified) . 

3.4.3 Command Decoder Option Table 

Five words are reserved beginning at location 17642 to store 
the various options specified in the command line. The format 
of these five words is as follows: 








1 


2 


3 


4 


5 


6 


7 


e 


9 


10 


11 


17642 


* 


HIGH ORDER 11 BITS OF 
= N OPTIONS 


17643 


A 


6 


C 


D 


E 


F 


6 


H 


I 


J 


K 


L 


17644 


M 


N 





P 


Q 


R 


S 


T 


u 


V 


W 


X 


17645 


Y 


Z 





1 


2 


3 


4 


5 


6 


7 


8 


9 


17646 


LOW ORDER 12 BITS OF-N OPTIONS 



Each of these bits corre- 
sponds to one of the pos- 
sible alphanumeric option 
switches. The correspond- 
ing bit is 1 if the switch 
was specified, otherwise. 



*Bit of location 17642 is 
if the command line was 
terminated by a carriage re- 
turn, 1 if it was terminated 
by an ALT MODE. 
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NOTE 

If no =n option is specified, the Command De- 
coder zeroes 17646 and bits 1 to 11 of 17642. 
Thus, typing =0 is meaningless since the user 
program cannot tell that any option was speci- 
fied. 



3.4.4 Example 

To clarify some of the preceding, consider the interpretation 
of the following command line: 

*BIN[lj3] ,<PTR: , ,DTA2 : PARA, MAIN /h=lA200$ 

If this command line is typed to PALS, it would cause assembly 
of a program consisting of four separate parts : two paper 
tapes, one file named PARA. PA on DTA2 , and one file named 
MAIN. PA also on DTA2. The binary output is placed on a file 
named BIN.BN on device DSK, for which only 10 blocks need be 
allocated. No listing is generated. In addition, automatic 
loading of the binary output is specified by the /L option, 
with the starting address given as 4 200 in field 1. Finally, 
the line is terminated by the ALT MODE key (which echoes as $) 
causing a return to the Keyboard Monitor after the program is 
loaded. 

In the case of this example, the Command Decoder returns to 
PALS with the following values in the system tables: 



NOTE 

The entries for PTR (where no input file name is 
specified) have a starting block number and file 
size of zero. This is always true of the input 
table for a non-file structured device, or a file 
structured device on which no file name is given. 
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17600 



17604 
17605 

17616 
17617 



17620 
17621 



17622 
17623 



17624 
17625 



17626 
17627 

17641 
17642 

17643 

17644 

17645 

17646 



0242 
0211 
1600 
000(2 
0000 



0016 
0000 



0016 
0000 



0127 
0100 



0007 
0105 



4001 

0001 

0000 

0000 

4200 



■ DSKI IS DEVICE NUMBER 2 



) FILE NAME IS BIN 



-NULL EXTENSION 

REMAINING ENTRIES 
IN OUTPUT TABLES 
ARE ZERO 



FIRST ptr; input 



SECOND ptr; input 



DTA2: PARA. F% IS 5 BLOCKS LONG, 
BEGINNING AT 1008 



I DTA2:MAIN.PA is 256(0 or MORE BLOCKS 
f LONG, BEGINNING AT BLOCK 1058- 

n REMAINING ENTRIES 
t > IN INPUT TABLES 
rj ARE ZERO. 

LINE WAS TERMINATED BY ALT MODE 



> /L WAS ONLY OPTION SWITCH SPECIFIED 



= 14200 WAS SPECIFIED 



3.5 Special Mode of the Command Decoder 



Occasionally the user program does not want the Command Decoder 
to perform the LOOKUP on input files, leaving this option to 
the user program itself. For example CONVRT, which translates 
Disk Monitor format DECtapes to PS/8 format DECtapes, cannot 
permit an erroneous LOOKUP to occur on DECtapes that are not 
in PS/8 format. The capability to handle this case is provided 
in the PS/ 8 Command Decoder. This capability is generally re- 
ferred to as the "special mode" of the Command Decoder. 
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3.5.1 Calling the Command Decoder Special Mode 

The special mode call to the Command Decoder is identical to 
the standard DECODE call except that the assumed input file 
extension, specified by ARG(l) , is equal to 5200. The value 
5200 corresponds to an assumed extension of ".*", which is 
illegal. Therefore, the special mode of the Command Decoder 
in no way conflicts with the normal mode. 

3.5.2 Operation of the Command Decoder in Special Mode 

In special mode the Command Decoder is loaded and inputs a 
command line as usual. The appearance of the command line is 
altered by the special mode in these respects: 



a. Only one output file can be specified. 

b. No more than five input files can be speci- 
fied, rather than the nine acceptable in 
normal mode. 

c. The character asterisk (*) is legal in file 
names and extensions, both in input files 

and on output files. It is strongly suggested 
that this character be tested by the user pro- 
gram and treated either as a special option 
or as an illegal file name. The user program 
must be careful not to ENTER an output file 
with an asterisk in its name as such a file 
cannot be manipulated or deleted by the standard 
system programs. 

The output and option table set up by the Command Decoder is 
not altered in special mode. Entries in the input table are 
changed to the following format: 



1 2345678910 11 



WORD 1 
WORD 2 
WORD 3 
WORD 4 
WORD 5 





4 -BIT DEVICE 
NUMBER 


FILE NAME 
CHARACTER 1 


FILE NAME 
CHARACTER 2 


FILE NAME 
CHARACTER 3 


FILE NAME 
CHARACTER 4 


FILE NAME 
CHARACTER 5 


FILE NAME 
CHARACTER 6 


FILE EXTENSION 
CHARACTER 1 


FILE EXTENSION 
CHARACTER 1 



BITS 0-7 ARE 
ALWAYS 



V INPUT FILE NAME 
/ 6 CHARACTER 



FILE EXTENSION 
2 CHARACTERS 
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The table entry for the first input file is in locations 17605 
to 17611; the second in locations 17612 to 17616; the third 
in locations 17617 to 17623; the fourth in locations 17624 
to 17630; and the fifth in locations 17631 to 17635. A zero 
in word 1 terminates the list of input files. If word 2 of 
an entry is zero, no input file name was specified. 
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CHAPTER 4 



USING DEVICE HANDLERS 



A device handler is a system subroutine that is used by all 
parts of the PS/8 system and by all standard system programs 
to perform I/O transfers. All device handlers are called in 
the same way and they all perform the same basic operation: 
reading or writing a specified number of 128 word records* 
beginning at a selected core address. 

These subroutines effectively mask the unique characteristics 
of different I/O devices from the calling program; thus, pro- 
grams that use device handlers properly are effective "device 
independent" . Changing devices involves merely changing the 
device handlers used for I/O. 

PS/8 device handlers have another important feature. They are 
able to transfer a number of records as a single operation. 
On a device like DECtape this permits many blocks of data to 
be transferred without stopping the tape motion. On a disk, 
a single operation could transfer an entire track or more. 
This capability significantly increases the speed of operation 
of PS/8 programs, such as PIP, that have large buffer areas. 

4.1 Calling Device Handlers 

Device handlers are loaded into a user selected area in field 
by the FETCH function. FETCH returns in ARG(l) the entry 
point of the handler loaded. The handler is called by perform- 



*The word "record" is defined to mean 128 words of data; thus, 
a PS/8 block consists of two 128 word records. 
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ing a JMS to the specified entry point address. It has the 
following format: 

CDF N /WHERE N IS THE VALUE OF THE CURRENT 

/PROGRAM INSTRUCTION FIELD TIMES 10 (OCTAL) 

CIF /DEVICE HANDLER ALWAYS IN FIELD 

JMS I ENTRY 

ARG(l) /FUNCTION CONTROL WORD 

ARC (2) /BUFFER ADDRESS 

ARC (3) /STARTING BLOCK NUMBER 

JMP ERR /ERROR RETURN 

/NORMAL RETURN (I/O TRANSFER COMPLETE) 

ENTRY, /ENTRY CONTAINS THE ENTRY POINT OF THE 

/HANDLER, DETERMINED WHEN LOADED BY FETCH 

As with calls to the USR, it is important that the Data Field is 
set to the current program field before the device handler is 
called. On exit from the device handler, the Data Field will 
remain set to the c\xrrent program field. 

ARG(l) is the function control word, and contains the following 
information: 



Bit (s) Contents 

Bit for an input operation^ 

1 for an output operation. 

Bits 1 to 5 The number of 12 8 word records to be 

transferred must not be 0. 

Bits 6 to 8 The memory field in which the transfer 

is to be performed. 

Bits 9 to 11 Device dependent bits, can be left zero. 

Currently only bit 11 is used; on DEC- 
tape bit 11 determines the direction in 
which the tape is started. If bit 11 is 
the tape starts in reverse. If bit 11 
is 1 the tape starts forward.* All 
other handlers ignore these bits at 
present. 



*Starting forward saves time as long as the block number, ARG(3) , 
is seven or more blocks greater than the number of the block at 
which the tape is currently positioned. 
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ARG(2) is the starting location of the transfer buffer. 

ARG(3) is the number of the block on which the transfer is to 
begin. The user program initially determines this value by 
performing a LOOKUP or ENTER operation. After each transfer 
the user program should itself add to the current block 
number the actual number of blocks transferred, equal to one- 
half the number of 128 word records specified, rounded up if 
the number of records was odd. 

There are two kinds of error returns: fatal and non-fatal. 
When the error return occurs and the contents of the AC are 
negative the error is fatal. A fatal error can be caused by 
a parity error on input, a write lock error on output, or an 
attempt to write on a read-only device (or vice versa) . The 
meaning can vary from device to device, but in all cases it is 
serious enough to indicate that the data transferred, if any, 
is invalid. 

When the error return occurs and the contents of the AC are 
greater than or equal to zero, a non-fatal error has occurred. 
This error always indicates detection of the logical end-of-file. 
For example, when the paper tape reader handler detects the end 
of a paper tape it inserts a CTRL/Z code in the buffer and takes 
the error exit with the AC equal to zero. While all non-file 
structured input devices can detect the end-of-file condition, 
no file structured device can; and no device handler takes the 
non-fatal error return when doing output. 

The following restrictions apply to the use of device handlers: 

a. Bits 1 to 5 of the function control word, ARG{1) , 
must not be zero as this value is currently unde- 
fined. 

b. The user program must never specify an input into 
locations 7600 to 7777 or 17600 to 17777 or the 
page(s) in which the device handler itself resides. 
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c. Note that the amount of data transferred is given 
as a number of 128 word records, exactly one half 
of a PS/ 8 block. Attempting to output an odd num- 
ber of records can change the contents of the last 
128 words of the last block written. 

d. The specified buffer address does not have to begin 
at the start of a page. The specified buffer cannot 
overlap fields, rather the address will "wrap around" 
in a single field. For example, writing two records 
from location 07600 would output 07600 to 07777 and 
page of field 0, not field 1. 

4.2 Device Dependent Operations 

This section describes briefly the operation of each of the stan- 
dard PS/8 device handlers, including normal operation, any special 
initialization operations for block 0, terminating conditions, 
and response to control characters typed at the keyboard. Further 
information on device handlers can be found in Chapter 5. 

4.2.1 Teletype (TTY) 

a. Normal Operation 

This handler inputs characters from the Teletype key- 
board and packs them into the buffer or unpacks charac- 
ters from the buffer and outputs them to the teleprintejr . 
It functions properly only on ASCII data. 

On input, characters are echoed as they are typed. Fol- 
lowing a carriage return, a line feed character is in- 
serted into the input buffer and printed on the Teletype. 

b. Initialization for Block 
None. 

c. Terminating Conditions 

On input, detection of a CTRL/Z causes a CTRL/Z to be 
placed in the input buffer, the remaining words of the 
buffer filled with zeros, and a non-fatal error to be 
returned. On output, detection of a CTRL/Z character 
in the output buffer causes output to be terminated and 
the normal return to be taken. There are no fatal errors 
associated with the Teletype handler. 
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d. Teletype Interaction 

CTRL/C forces a return to the Keyboard Monitor. CTRL/Z 
forces an end-of-file on input (see c) . CTRL/0 termi- 
nates printing of the contents of the current buffer on 
output. 



4.2.2 High-Speed Paper Tape Reader (PTR) 



a. Normal Operation 

This handler inputs characters from the high-speed paper 
tape reader and packs them into the buffer. 



b . Initialization for Block 

The handler prints an up-arrow (t)* on the teleprinter 
and waits for the user to load the paper tape reader. 
By typing any single character (except CTRL/C) the user 
initiates reading of the paper tape. 



c. Terminating Conditions 

Detection of an end-of-tape condition, indicated by the 
failure to get a character in a specified period of time, 
causes a CTRL/Z to be entered in the buffer, the remain- 
ing words of the buffer to be filled with zeros, and a 
non-fatal error to be returned. Attempting to output to 
the paper tape reader causes a fatal error to be returned. 



d. Teletype Interaction 

Typing CTRL/C forces a return to the Keyboard Monitor. 

4.2.3 High-Speed Paper Tape Punch (PTP) 

a. Normal Operation 

This handler unpacks characters from the output buffer 
and punches them on the paper tape punch. 

b. Initialization for Block 
None. 



*0n some Teletypes , up-arrow is replaced by the circumflex ( 
character. 
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c. Terminating Conditions 

Attempting to input from the paper tape punch causes a 
fatal error to be returned. There are no non-fatal 
errors associated with this handler. 



d- Teletype Interaction 

Typing CTRL/C forces a return to the Keyboard Monitor. 

4.2.4 Line Printer (LPT) 

a. Normal Operation 

This handler unpacks characters from the buffer and 
prints them on the line printer. The characters hori- 
zontal tab (ASCII 211) causes sufficient spaces to be 
inserted to position the next character at a "tab stop" 
(every eighth column, by definition) . The character 
vertical tab (ASCII 213) causes nine line feeds to be 
output. The character Form Feed (ASCII 214) causes 
a skip to the top of the next page. Finally, the 
handler maintains a record of the current print column 
and starts a new line after 80 columns have been printed. 
This handler functions properly only on ASCII data. 

b. Initialization for Block 

Before printing, the line printer handler issues a 
form feed to space to the top of the next page. 

c. Terminating Conditions 

On detection of a CTRL/Z character in the buffer, the 
line printer handler issues a form feed and immediately 
takes the normal return. Attempting to input from the; 
line printer forces a fatal error to be returned. Also 
if the line printer error flag is set a fatal error is 
returned. There are no non-fatal errors associated with 
the line printer handler. 

d. Teletype Interaction 

Typing CTRL/C forces a return to the Keyboard Monitor. 
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4.2.5 Card Reader (CDR) 



a. Normal Operation 

This handler reads characters from the card reader and 
packs them into the input buffer. Trailing spaces (blank 
columns) on a card are deleted from input. The handler 
can accept only alphanumeric format data on cards (the 
DEC029 standard card codes are used) . 

b. Initialization for Block 
None. 

c. Terminating Conditions 

A card which contains an underline character in column 1 
(an 0-8-5 punch) with the remaining columns blank is an 
end-of-file card. In addition, after reading each card 
the handler checks to see if a CTRL/Z was typed at the 
keyboard. After either an end-of-file card or a CTRL/Z 
being typed, a CTRL/Z is inserted in the buffer, the 
remaining words of the input buffer are filled with zeros, 
and a non- fatal error is returned. Attempting to output 
to the card reader causes a fatal error to be returned. 

d. Teletype Interaction 

Typing CTRL/C forces a return to the Keyboard Monitor. 
Typing CTRL/Z forces an end-of-file to occur (see c) . 

4.2.6 File Structured Devices 



a. Normal Operation (DECtape, LINCtape, DF32, RFJ3f8, and 

RK8) 

These handlers transfer data directly between the device 
and the buffer. 



b. Initialization for Block 
None. 
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c. Terminating Conditions 

A fatal error is returned whenever the transfer caused 
one of the error flags in the device status register to 
be set. For example, a fatal error would result if a 
parity error occurred on input, or a write lock error 
occurred on output. The device handlers generally try 
three times to perform the operation before giving up 
and returning a fatal error. There are no non-fatal 
errors associated with file structured devices. 



d. Teletype Interaction 

Typing CTRL/C forces a return to the Keyboard Monitor, 

NOTE 
The system device handler does NOT re- 



spond to a typed CTRL/C. 
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CHAPTER 5 



RECONFIGURING THE PS/8 SYSTEM 



In the instructions on building PS/8 in the 8K Programming 

* 
System User's Guide , mention is made of the several paper 

tapes marked CONFIG distributed with each system. Each PS/8 

system contains the source file CONFIG. PA, either on DECtape, 

paper tape (in two parts) , or LINCtape. CONFIG contains all 

configuration dependent parts of the PS/8 system, including 

all device handlers, device dependent system tables, bootstrap 

routines, and system device handlers. 

The problem of changing the system configuration is reduced 
to editing the CONFIG file and assembling the result to pro- 
duce a new binary tape. This new binary tape is then used in 
building a modified system. The following chapter describes 
in detail the ways in which CONFIG can be modified. 

5.1 Conditional Assembly of CONFIG 

The source file CONFIG. PA contains a number of conditional 
symbols. These are symbols that, in conjunction with some 
IFDEF, IFNDEF, IFZERO, or IFNZRO pseudo-ops, cause various sec- 
tions of the program to be assembled with PALS. Creating 
standard system variations requires the proper definition of 
one or more of these parameters. 

♦Although it is not explicitly stated, the instructions given 
could also be used to create a PS/8 System DECtape. Mount the 
tape to be built on Unit j3 , WRITE ENABLEd, and follow the in- 
structions given. The binary tape marked "DECtape CONFIG" 
would be used in place of one of the disk CONFIG' s. 
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5.1.1 System Device Selection 

One and only one of the system device parameters can be 
defined and assigned a non-zero value. 

a. RF08 Disk System 

Defining RFj38 = n, where n is 1,2,3, or 4 
causes an n disk RFj38 to be the system device. 
For example: 

RFjef8=2 

would generate a 512K RF/RS08 system. 

b. DF32 Disk System 

Defining DF3 2 = n, where n is 1,2,3, or 4 
causes an n disk DF3 2 to be the system device. 
For example : 

DF3 2=2 

would generate a 64K DF/DS32 system. 

NOTE 

Because PS/8 alone takes 14K of the 
system device, it is felt that a 
single disk DF32 has insufficient 
storage for PS/8. The system is 
not supported by DEC on a 32K disk. 

c. RK8 Disk System 

Defining RK8=1 causes an RK8 disk to be the 
system device, generating an RK8 system. 

d. PDP-12 LINCtape System 

Defining LINCSyS=n, where n is 1 or 2 causes 
LINCtape unit to be the system device. If 
LINCSYS=1, the default file storage device 
(device DSK) is also LINCtape unit 0. If 
LINCSYS=2, the default file storage device 
is LINCtape unit 1, which is to be preferred 
as it minimizes tape motion. 
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NOTE 

When LINCSYS is the specified system parameter, 
the user must be certain to explicitly specify 
LINCTAPE=1 (see section 5.1.2), otherwise DEC- 
tape rather than LINCtape handlers would be in- 
cluded in the system. 

e. DECtape System 

If no other system device parameters are speci- 
fied, DECtape unit is the default system de- 
vice. One can also define DECTAPE=n, where n 
is 1 or 2 to cause DECtape unit to be the 
system device. If DECTAPE=1 , the default file 
storage device (device DSK) is DECtape unit 0. 
If DECTAPE=2, the default file storage device 
is DECtape unit 1, which is to be preferred as 
it minimizes tape motion. 

5.1.2 Optional Device Parameters 

The standard system, generated by defining one of the system 
device parameters, contains the following device handlers: 

Device Code Meaning 

SYS Selected system device 

TTY Teletype 

PTR High-speed paper tape reader 

PTP High-speed paper tape punch 

CDR Card reader (CR8 or CMS) 

LPT LPjelS Line printer 

DTAj2(-DTA7 Handlers for eight DECtape drives 

DSK Default file storage device, always the same 

as the system device unless LINCSYS=2 or 
DECTAPE=2 are used. 

These device handlers can be replaced by others by defining one 
of the following parameters: 
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LINCtape handlers 

If the computer is a PDP-12, it is necessary 
to replace the standard DECtape handlers with 
LINCtape handlers. This must be done explicitly 
by defining LINCTAPE=1. 

LP12 Line Printer, Type 645 

A small number of systems have the old style 
line printer rather than the new LPj2f8. Defin- 
ing LP08=0 causes a device handler for the LP12 
(Type 645) line printer to replace the standard 
LP08 handler. 

NOTE 

The FORTRAN run time I/O routines, with 
the exception of the device-independent 
I/O routines, do not use PS/8 handlers. 
Therefore, in FORTAN use the statement 
WRITE (3,n) only works on the LPj2i8 line 
printer. To use a different printer the 
FORTRAN subroutine UTILTY.SB (available 
on source DECtape #3) must be modified. 

Low-Speed Paper Tape 

The standard Teletype handler (TTY) checks for 
-tC and +Z control characters (CTRL/C and CTRL/Z) . 
To enable the handler to work on terminals that 
utilize parity ASCII, the handler ignores the 
leading bit when checking for these characters. 
For this reason non-ASCII input is not acceptable 
to the Teletype handler. 

While this is no problem to systems having a 
high-speed paper tape reader, those who lack one 
would be unable to load any binary paper tapes 
under PS/8. For this reason there is a special 
low-speed paper tape handler available in CONFIG. 
To assemble this option, define the following: 

N0HSPT=1 

When N0HSPT=1 is used the PTR and PTP handlers 
are replaced with new Teletype routines. (The 
names of the new handlers remain PTR for input 
and PTP for output. ) 
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WARNING! 






The 


source of CONFIG released in 


November 


1970 


contains an error in this 1 


ow- 


speed 


paper tape routine. 


To correct 


this , in- 1 


sert 


the following 


code immediately 


before 


the 


terminating $ in CONFIG. PA: 








IFNZRO NOHSPT 


<*6522 








RTL 










RTL 










DCA PTR 










TAD PTR > 








This 


omission will 


be corrected 


in 


later 


releases of CONFIG 









Like the high-speed paper tape reader handler, the 
low-speed handler prints a f character before 
reading a tape. The user then loads the tape to 
be read in the low-speed reader and sets the Tele- 
type reader switch to START. While reading from 
the low-speed reader, do NOT type anything on the 
keyboard. At the end of the reading process, turn 
the Teletype reader control switch to STOP and re- 
move the tape. 

The PTR and PTP handlers differ from the standard 
TTY handler in that they ignore control characters. 
The PTR handler recognizes an end-of-tape condition 
by "timing out" the low- speed reader - it expects 
the keyboard/reader flag to be reset within 150 ms 
and if it is not, an end-of-file occurs. At the 
end-of-file a CTRL/Z is automatically inserted in 
the buffer following the last character read. 



5.1.3 Other Options 

There is one more option that can be used in building a non- 
standard PS/8 system. The parameter DIRECT determines whether 
or not the system directory is to be zeroed when the system is 
rebuilt. Defining DIRECT=1 causes a new system to be built 
without zeroing the old directory. This feature is useful 
when reconfiguring a system to avoid having to reload all of 
the files currently on the system device. 
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5.1.4 Example 

As an example of reconfiguring a PS/8 system, suppose a machine 
has the following configuration: 

a. PDF- 8/1 computer 

b. DECtape 

c. RFjZfS disk with two RSj38's (768K of storage) 

d. Type 645 line printer (LP12) 

e. High-speed reader/punch 

f. Card reader 

The following steps would be taken to build a system tailored 
to the above configuration. 

a. Build the system in the usual manner using the 
RFj2f8 CONFIG provided and the instructions in 
the 8K Programming System User's Guide . 

b. Use PIP to put the file CONFIG. PA on the disk. 

c. Execute the following commands: 

.R EDIT 
*PARA.PA < 

#A 

/PARAMETER FILE 

RFJ08=3 /3 PLATTER RFjEiS SYSTEM 

LPjaf8=J2r /OLD STYLE LINE PRINTER 

DIRECT=1 /PRESERVE SYSTEM DIRECTORY 

#E 

• R PAL8 

*PTP:< PARA, CONFIG 

d. Use the paper tape punched by PAL8 as the CONFIG 
binary in building a new system. 

e. Finally, since the DIRECT parameter prevented the new size o 
the system device (changed from 256K to 768K for this ex- 
ample) from being automatically written in the directory, 

it must be updated by the following operation: 

.R PIP 

*SYS: < SYS:/S=1 

ARE YOU SURE? 

YES 
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5.2 Building a System on DECtape or LINCtape 

To avoid the time involved in rebuilding the system off paper 
tape each time it is changed, the binary tapes of PS/8, the 
Command Decoder (CD) , and CONFIG can be placed on DECtape (or 
LINCtape) and the system built by the following procedure: 

a. Put the system tape on unit and the tape, 
containing the binary files PS8.BN, CD.BN, 
and CONFIG. BN on unit 1 (where CONFIG. BN cor- 
responds to the system configuration) . 

b. Bootstrap the DECtape (or LINCtape) system 
and execute the following command: 

.R ABSLDR 

*DTA1 : PS 8 , CONFI G/G 

c. The system should halt with 7777 in the AC 
(if not, an error has occurred, try again 
from step b) ; press CONTINUE to proceed. 
If the system device is not being changed, 
the build is complete at this point, other- 
wise execute the following command: 

.R ABSLDR 

*DTA1 :PS 8 , CONFIG ,CD/G 

d. The new system is built and responds to the 
RETURN key by printing a dot when ready to 
accept input. Now, if necessary, transfer 
files to the new system device with PIP. 

Of course the above procedure is not limited to DECtape or LINC- 
tape. The files PS8.BN, CD.BN, and CONFIG. BN could just as 
easily be placed on a disk and loaded from there. The example 
is intended to illustrate a useful alternative technique for 
building a system. 

5.3 Adding New Device Handlers 

PS/8 system programs have been organized so that all non- 
Teletype I/O is done via calls to standard system device 
handlers. Any new device for which a handler is written can 
be added to the system by changing CONFIG and rebuilding the 
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system. Once this is done, all existing system programs are 
able to use the new device. This flexibility is one of the 
most important features of the PS/8 system. 



NOTE 

In the November 19 70 version of PS/8 the follow- 
ing cannot use devices that require two page de- 
vice handlers: 

a. GET, RUN, and SAVE operations, 

b. CONVERT output device must have a one-page 
handler , 

c. PIP cannot perform /Z or /D operations on 
devices requiring two page handlers, 

d. SABR cannot use two page handlers, and 

e. General I/O in FORTRAN, READ (4, n) and WRITE 
(4,n), cannot use two page device handlers. 

Future versions of PS/8 will not contain these 
restrictions . 



The following sections describe in detail how to add a new de- 
vice handler. For further information on device handlers, the 
reader should consult Chapter 4. Examples of standard handlers 
can be found in the listing of CONFIG which can be ordered from 
the DEC Program Library (DEC-P8-MW3A-LA) . 

5.3.1 Writing Device Handlers 

A device handler is a page-independent one or two page long 
subroutine. The device handler must run properly in any single 
page or two contiguous pages in field (except 0000 to 0177 
or 7600 to 7777) . All device handlers have the same calling 
sequence : 
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CDF N 

GIF 

JMS I ENTRY 

FUNCTION 



BUFFER 

BLOCK 

ERROR 

NORMAL 



/N IS CURRENT FIELD TIMES 10 (OCTAL) 

/DEVICE HANDLER LOCATED IN FIELD 

/ENTRY IS DETERMINED BY USR "FETCH" 

/FUNCTION IS BROKEN DOWN AS FOLLOWS: 

/ BIT 0=0 FOR READ 

/ BIT " 1 FOR WRITE 

/ BITS 1 TO 5 = NUMBER OF PCS TO TRANSFER 

/ BITS 6 TO 8 = FIELD FOR TRANSFER 

/ BITS 9 TO 11 = DEVICE DEPENDENT BITS 

/CORE ADDRESS OF TRANSFER BUFFER 

/STARTING BLOCK NUMBER FOR TRANSFER 

/ERROR RETURN, AC>=;2( MEANS END-OF-FILE 

/ AC<;af MEANS FATAL ERROR 

/NORMAL RETURN 



The device handler reads or writes a number of 128 word records 
beginning at the selected block. In general, device handlers 
should conform to the following standards: 



a. On normal return from a device handler the AC is 
zero and the DATA FIELD is always restored to 
its original entry value. 

b. Although the starting block number has true sig- 
nificance only for file structured devices, 
handlers for non-file structured devices can 
check the block number and perform initialization 
if the block number is zero. For example, the 
line printer handler outputs a form feed before 
printing when the specified block number is zero. 

c. Handlers should be written to be as foolproof as 
possible. Examples of typical user errors are: 
calling handler with non-zero AC (always perform 
a CLA in the handler) ; trying to read on a write- 
only device, or trying to write on a read-only 
device (give a fatal error return) ; specifying 
pages to be transferred (accept as meaning no ac- 
tual transfer is to take place) ; or attempting to 
access a nonexistent block (give a fatal error re- 
turn) . 

d. Device handlers normally check to see if a CTRL/C 
(ASCII 203) has been typed by the user. If one 
has, the handler aborts I/O and JMP ' s to location 
7600 in field 0. 
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e. Device handlers should be able to detect standard 
error conditions like checksum or parity errors. 
Whenever possible, several attempts to perform 
the transfer should be made before aborting I/O 
and taking the error exit. In addition, when 
operator intervention is required, the handler would 
normally wait for the action rather than take a 
fatal error exit. For example, if the paper tape 
punch is not turned on, the PTP handler waits for 
the punch to be turned on. 

f. By convention, in any handler for a device (like 
DECtape) that can search either forward or back- 
ward for a block, Bit 11 of the function word (one 
of the device'-dependent bits) controls the start- 
ing direction of the search. Bit 11 is a 1 if 
the starting direction is forward and a if it 

is reverse. The other two device dependent bits 
are not assigned any significance at the present 
time. 

g. Remember that the user specifies a multiple of 
128 words to transfer, whereas the transfer starts 
at the beginning of a 256 word block. This means 
that the handler must provide the capability of 
reading or writing the first half of a block. 
When writing the first half of the block, the con- 
tents of the second half of the block can be 
altered. 

h. The entry point to a two page device handler must 
be in the first page. 

i. A number of handlers can be included in the one or 
two pages of code. Where more than one handler is 
included in a single handler subroutine, the handlers 
are called co-resident. Co-resident handlers are 
always brought into core together. For example, 
all eight DECtape handlers fit into one page; hence, 
the DECtape handlers are co-resident. One restric- 
tion on co-resident handlers is that if they are 
two pages long all entry points must be in the first 
page. 

j. The USR, while doing file operations, maintains in 
core the last directory block read in order to re- 
duce the number of directory reads necessary. The 
proper functioning of this feature depends on the 
fact that every handler for a file-structured device 
on a single system has a unique entry point relative 
to the beginning of the handler. The relative entry 
points currently assigned for file structured handlers 
are : 
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Device Handlers 



Relative Entry Points 



MAGtapes 

System Device Handler 

DECtape or LINCtape 

RKAJ2( 

RKAl 

RKA2 

RKA3 



to 6 

7 
10 to 17 

20 

21 

22 

23 



k. If the device is block oriented (such as DECtape, 
LINCtape, or disk), then the handler transfers 
data directly with no alteration. However, if 
the device is character oriented (such as a paper 
tape reader. Teletype, or line printer) , the 
handler is required to pack characters into the 
buffer on input and unpack them on output. The 
standard PS/8 character packing format puts three 
8-bit characters into two words as follows : 



WORD * 
WORD 2 



CHARACTER 3 
BITS 0-3 


CHARACTER 1 


CHARACTER 3 
BITS 4-7 


CHARACTER 2 



When packing characters on input, the character 
CTRL/Z (octal 232) is inserted at the logical 
end-of-file (for example, at the end of the tape 
in the paper tape reader handler) . Following 
CTRL/Z, the remaining words of the input buffer 
should be zeroed. 

The device handler, whether one or two pages 
long, must be completely page independent: it 
can be loaded and executed in any page in field 
except page and 7600 to 7777. Page independ- 
ent code can have no address constants. For ex- 
ample, the following routine illustrates how a 
table lookup would be performed in page independ- 
ent and non-page independent code : 



Non-Page Independent Code 

TAD INDEX 
TAD (TABLE) 
DCA TEMP 
TAD I TEMP 



Page Independent Code 

TAD INDEX 

TAD (TAD TABLE) 

DCA .+1 





INDEX, 
TEMP , 
TABLE , . . 



INDEX, 
TABLE , 
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The page independent method works only because 
the table must be in the same page. Writing _ 
page independent code for one page handlers is 
quite easy. Two page handlers are considerably 
more difficult, since communication between the 
two pages requires the handler to determine where 
in core it was loaded. Specifically, two page 
handlers often include one-time initialization 
code that performs a JMS to determine where it 
is. The card reader handler in CONFIG should 
be studied by anyone who writes a two page 
handler. 



5.3.2 Editing Device Handlers Into CONFIG 

Once a new handler has been written and thoroughly debugged as 
a stand-alone subroutine, it can be added to the system by edit- 
ing the handler into CONFIG. PA, changing certain sections in 
CONFIG, reassembling the result, and building a new system from 
the binary tape produced. Follow the following steps to build a 
new PS/8 system: 

a. Edit the handler into CONFIG. The handler should 
be origined into the areas of core between 4400 
to 5577 or 14000 to 17577. 

b. Select a system block on which to write the handler. 
The first device handler storage block is "DVHORG"*, 
and the last available block for device handlers 

is "DVHORG" + 7 (blocks 16 [octal] to 2 5 [octal] in 
the current system) . Existing device handlers re- 
quire blocks "DVHORG" through "DVH0RG"+4. 

c. In the generation section of CONFIG (the subroutine 
"WRDEVH") edit in a call to the system handler to 
write the desired device handler onto the selected 
device handler storage block. The calls already 
included in this subroutine should provide suffi- 
cient examples. 

d. Select a device number for the new device. The 
number must be in the range 3 to 15 because device 
number 1 is reserved for SYS and device number 2 
is reserved for DSK. The number selected will re- 
move some standard device from the system; the de- 
vice removed should be a "useless" one (for example, 
remove DTA7 if the system has less than 8 DECtape 



*Names in quotes refer to symbols used in CONFIG. PA. 
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drives) . If the handler contains co-resident 
device handlers , several device numbers must be 
selected (not necessarily consecutive numbers) . 



e. Edit into CONFIG the new entries for the Perma- 
nent Device Name Table ("SDNAME") and the Device 
Handler Information Table ("SDVHND"). In both 
cases the device number is an index to the table 
entry to be changed. See Appendix B for informa- 
tion about entries in these tables. Remember 
that entries must be made for all co-resident 
handlers. 

NOTE 

When considering a name for the device, 
be certain to select one that does not 
conflict with an existing device name. 
See section B.3.1. 

f. Check the device Type Table explained in section 
B.3.5. If the new device is similar to an exist- 
ing device then assign the new device the same 
device type code as the existing device. (If the 
device is file structured, it can only be similar 
to devices of the same size.) Otherwise select 

a new device type in the range 21 to 77 (octal) . 
Now edit into CONFIG a new entry in the Device 
Control Word Table ("DCB"), see section B.3.5 
to get the format for an entry. Again, entries 
must be made for all co-resident handlers. 

g. If there is any device other than the system de- 
vice that should be the new default file storage 
device (DSK) , change the entries for device num- 
ber 2 in the Device Handler Information Table 
("SDVHND") and the Device Control Word Table ("DCB") 
to be identical to the entries for the selected 
device. 

NOTE 

The new device DSK will no longer be 
equivalent to the system device, hence 
its device handler will no longer be 
permanently resident. The entry in the 
Device Handler Residency Table (see sec- 
tion B.3.3) must be zeroed. This is done 
by editing the following code into the 
end of CONFIG: 

*1^50',0 /DSK IS NON-RESIDENT 



*Names in quotes refer to symbols used in CONFIG. PA. 
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h. All the edits to CONFIG are now complete. 
Assemble the new source of CONFIG and re- 
build the system by following the instruc- 
tions given in section 5.1. 

i. Finally, if the new device is a file struc- 
tured device for which it was necessary to 
select a new device type code in step f, 
the Device Length Table in the file PIP.SV 
must be patched so that PIP can perform /Z 
and /S operations on the device correctly. 
This can be done easily by using the system 
ODT as follows : 

Teleprinter Output Notes 

.GET SYS: PIP 
.ODT 

13 6nn/0jZfj3|2f xxxx where nn is the new de- 
vice type code in octal 
+C and xxxx is minus the 

.SAVE SYSrPIP highest PS/8 block num- 
ber for the device, also 
in octal. 
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APPENDIX A 

PS/8 File Structures 

A.l File Directories 

Blocks 1 through 6 on all file structured devices are re- 
served for the file directory of that device. Six blocks 
are always allocated but all are not necessarily active at 
any given time. To minimize the number of directory reads 
and writes necessary, PS/8 fills one directory block com- 
pletely before overflowing onto a second block. Thus the user 
with only a few files can perform directory LOOKUPS and 
ENTERS faster than one with many files. 

The directory blocks are each structured according to the 
following format: 



ENTRY 



:* 



3778 



MINUS THE NUMBER OF ENTRIES 
IN THIS SEGMENT 



THE STARTING BLOCK NUMBER 
OF THE FIRST FILE IN THIS 
SEGMENT 



LINK TO NEXT SEGMENT- ZERO 
IF NO NEXT SEGMENT. 



FLAG WORD- POINTS TO LAST WORD 
OF TENTATIVE FILE ENTRY IN 
THIS SEGMENT 



MINUS THE NUMBER OF 
ADDITIONAL INFORMATION WORDS 



BEGINNING OF FILE ENTRIES 



END OF DIRECTORY BLOCK 



{DIRECTORY SEGMENTS ARE ALWAYS 
LOADED INTO LOCATIONS 1 1400 
TO 11777 BY THE USR.THIS 
POINTER IS EITHER OR BETWEEN 
1400 AND 1777 



TtHE NUMBER OF ADDITIONAL 
\) INFORMATION WORDS SPECIFIED 
1 MUST BE THE SAME IN ALL 
L DIRECTORY SEGMENTS 



f 



Locations through 4 of each directory block are called the 
segment header. 
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A. 1.1 Directory Entries 



There are three types of file directory entries 
file entry appears as follows: 



A permanent 



Loca- 
tion 



Contents 



Notes 






FILE NAME 
CHARACTER 1 


FILE NAME 
CHARACTER Z 




1 


FILE NAME 
CHARACTER 3 


FILE NAME 
CHARACTER 4 




2 


FILE NAME 
CHARACTER 5 


FILE NAME 
CHARACTER 6 




3 


FILE EXTENSION 
CHARACTER 1 


FILE EXTENSION 
CHARACTER 2 




4 






i 


ADDITIONAL 

. INFORMATION j 

WORDS 


■ 


N + 3 






N+4 


MINUS FILE LENGTH IN BLOCKS 





THE FILE NAME AND EXTENSION 
S IS FWCKEO IN SIXBIT ASCII 
(i,e.,"A"WOULD BE 01). 



N.THE NUMBER OF ADDITIONAL 
INFORMATION WORDS, IS GIVEN 
BY WORD 4 OF THE DIRECTORY 
HEADER. IF N # . THEN WORD 
4 OF THE ENTRY IS THE 
CREATION DATE OF THE FILE. 



Note - if word 3 is zero, the given file has a null extension, 



An empty file entry appears as follows: 



Loca- 
tion 



Contents 



ENTRY IS ALWAYS 0000 



MINUS THE NUMBER OF BLOCKS 
IN THIS EMPTY FILE 
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A tentative file entry appears as a permanent file entry with 
a length of zero. It is always immediately followed by an 
empty file entry. When the tentative file is entered in a 
directory, location 3 in the segment header becomes a pointer 
to this entry. The CLOSE function inserts the length word of 
the tentative file entry, making it a permanent file, and ad- 
justs the length of the following empty file entry (deleting 
that entry if the length becomes zero) . 

Whether or not there is a tentative file open on any device 
is determined by examination of bits 9 to 11 of the system Device 
Control Word Table (see section B.3.5) no t the contents of 
location 3 in the segment header. Zeroing these bits in the 
Device Control Word Table makes the active tentative file on 
the device inactive. The next time that the system has to 
write the directory segment, the inactive tentative file entry 
is removed. The distinction between active and inactive tenta- 
tive files is made so that PS/8 can avoid spending the time 
required to perform an extra read and write of the device direc- 
tory. 

A. 1.2 Number and Size of PS/8 Files 

All files on a PS/8 device must occupy a contiguous group of 
blocks on the device. The length of any file is indicated in 
its directory entry, and the starting block of the file is de- 
duced by adding together word 1 of the segment header and the 
lengths of all files whose entries precede it in the directory 
segment. 

Each directory segment must have enough unused words at the end 
to accommodate a permanent file entry (N+5 words, where N is the 
number of Additional Information Words). Thus, if N is the number 
of Additional Information Words the maximum number of permanent 
file entries in any one segment is : 

MAX = r 256-5 - (N+5)i r 246-N ] 
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Directory fragmentation (alternation of permanent file entries 
with empty file entries) reduces this maximum, and in the worst 
case the number of permanent file entries in any one segment is 
limited to : 



MIN 



- r 256-7 - (N+5) 1 = r 244-N ., 

- L 1^+7 J L N+7 J 



with N=l, MAX=40, and MIN=30. Since there are six segments in 
the directory, the maximum number of files possible (with N=l) 
would be 2 40. 

Finally, PS/8 devices are limited to 4095 blocks, each 256 
words long. Thus, the maximum size of any single PS/8 file 
structured device is 1,048,320 words. Blocks through 6 of the 
device are unavailable for file storage; therefore, the l£irgest 
possible file is 4088 blocks long, or 1,046,528 words. 

A. 1.3 Sample Directory 

The initial directory written when the PS/8 system is built 
looks as follows : 



Loca- 
tion 



Contents 



Notes 



SEGMENT / 
HEADER ^ 



PERMANENT 

FILE < 
ENTRY 



EMPTY 
FILE 
ENTRY I 14 




3778 



* THIS LEAVES 
PS/8 SYSTEM 



TWO ENTRIES 

FILE STORAGE STARTS AT BLOCK 709* 

NO ADDITIONAL DIRECTORY SEGMENTS 

NO TENTATIVE FILES 

ONE ADDITIONAL INFORMATION WORD 

FILE NAME IS "ABSLDR" 

FILE EXTENSION IS .SV 
DATE IS 10/31/70 
LENGTH IS FIVE BLOCKS 
EMPTY FILE 

LENGTH IS 12448 <676,q) BLOCKS - 

THIS IS DEPENDENT ON THE SYSTEM 
DEVICE USED, 676 IS THE VALUE FOR 
A OECTAPE SYSTEM. 



ROOM FOR THE 
AREAS 
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A. 2 File Formats 

There are three different standard file formats used by PS/8 
and associated system programs: 

ASCII and Binary files* 

Core Image files (.SV format) 

Relocatable FORTRAN library files (LIB8.RL is the 
only current example of this format) 

A. 2.1 ASCII and Binary Files 

ASCII and Binary files are packed three characters into two 
words, as follows: 



WORD 1 
WORD Z 



CHARACTER 3 
BITS 0-3 


CHARACTER 1 


CHARACTER 3 
BITS 4-7 


CHARACTER 2 



3 4 



The following conventions are used by PS/8 system programs: 



c. 



In ASCII files the character NULL (ASCII 0)2(0) 
is always ignored. 

In Binary files the binary data must be pre- 
ceded by one or more frames of leader/trailer 
code (ASCII 2)2^0 code) . The first character of 
binary data must be either 100 to 177 octal (an 
origin setting for absolute binary files) or 
240 to 257 octal (a COMMON declaration frame 
for relocatable binary files) . The end of binary 
data is indicated by one or more frames of leader/ 
trailer code. 

ASCII and Binary files are terminated by a CTRL/Z 
code (ASCII 232). In binary files, a CTRL/Z code 
occurring before the trailer code is treated as 
data rather than end-of~file. 



*Binary files can contain either absolute binary data (i.e., 
output from PALS) or relocatable binary data (i.e. , output from 
SABR) . 
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A. 2. 2 Core Image (.SV format) Files 

A core image file consists of a header block followed by the 
actual core image. The header block is called the Core Con- 
trol Block. The Core Control Block consists of the first 128 
words of the 256 word block reserved for that purpose. The 
second 12 8 words are unused. The Core Control Block is format- 
ted as follows : 



Loca- 
tion 



Contents 



Notes 



CORE CaVTROL BLOCK 



2K+3 



MINUS THE NUMBER OF CORE SEGMENTS 



CDF CIF (STARTING FIELD) 



STARTING ADDRESS 



JOB STATUS WORD 



«: 



3778 



I 



62N3 WHERE N IS THE 
"STARTING FIELD 



CORE SEGMENT 
' ' ) CONTROL DOUBLEWORDS 



t 



(K IS THE NUMBER OF 
CORE SEGMENTS J 



REMAINDER OF BLOCK 
IS UNUSED 



The format of the Job Status Word is as follows 



Bit Condition 



Bit 0=1 



Bit 1=1 



Meaning 

File does not load into locations to 1777 
in field 0. 

File does not load into locations to 1777 
in field 1. 



Bit 2=1 



Program must be reloaded before it can be 
restarted. 
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Bit Condition 
Bit 10 = 1 



Bit 11 = 1 



Meaning 

Locations to 17 77 in field need not be 
preserved when the Command Decoder is called. 

Locations to 1777 in field 1 need not be 
preserved with the USR is called. 



The Core Segment Doublewords control the reading and writing of 
the associated areas of core. The format of each entry is as 
follows : 



Loca- 
tion 




Contents 




Notes 


1 


CORE ORIGIN 


MULTIPLE OF 4008 


2 




NUMBER OF PAGES 
TO LOAD 


FIELD 
TO LOAD 




BITS AND 9-11 
ARE ZERO 



The core origin must be a multiple of 400g. The Core Segment 
Control Doublewords are sorted within the header block in order 
of decreasing field and increasing origin within the same field. 
There can be no more than 32, „ Core Segment Control Doublewords 
in any Core Control Block. 

The Core Control Block for the program at the time it is loaded 
into core is always saved in words 200p through 377„ of block 37g 
(one of the system scratch blocks) on the system device. It is 
placed there by the GET and RUN operations or by the ABSLDR or 
LOADER programs. This Core Control Block is used when performing 
a SAVE without arguments . 



NOTE 

The R command differs from the RUN command in that 
the program's Core Control Block is not written on- 
to the scratch area when using the R command. In 
order to SAVE a program that has been loaded by the 
R command all of the argument of the SAVE command 
must be explicitly stated. 
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A. 2. 3 Relocatable FORTRAN Library File 

A relocatable FORTRAN library consists of a library directory 
block followed by relocatable binary segments. The directory 
block has the following format: 



Loca- 
tion 


Contents 








Notes 





CH 1 




CH 


2 








1 


CH 3 




CH 


4 




NAME OF ENTRY IN 
^ SIXBIT ASCII PADDED 
WITH TRAILING BLANKS 


2 


CH 5 




CH 


6 






3> 


LOAD POINTER 




/a 

1 5 


! ADDITIONAL ENTR 

« 
• 


lES 

> 






S 


- 













e> 


, DENOTES END OF 
NAME ENTRIES 














Ni » 


: 








: 


•r 




— 


*. LOADER CONTROL WORD(S) 




— 


-^ END OF LOADER CONTROL 
■*■ WORDS FOR THIS ENTRY 


* 


• * 


" 
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The Load Pointer is a number between and 377j, which points 
(relative to the beginning of the block) to an array of Loader 
Control Words. The Loader Control Words have the following 
information: 



z 



•NUMBER OF PAGES OCCUPIED 
BY THIS SEGMENT AFTER 
LOADING 



D 



-(STARTING BLOCK OF RELOCATABLE 
BINARY DATA)- (DIRECTORY BLOCK #)-1 
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There can be one or more Loader Control Words for each 
entry. The Loader Control Words for an entry are termi- 
nated by a word of zero. The following is a simple directory 
block. 



Loca- 
tion Contents 



Notes 



LOADER 

CONTROL 

WORDS 

FOR "EXIT" 



LOADER 
CONTROL 
WORDS 
F0R"I0H" 13773 












1117 




1 


1040 


i 


2 


4040 




3 


0376 




4 


0530 




5 


1124 


' 


6 


4040 




7 


0373 




10 


0000 




11 


0000 


> 


12 


0000 


13 


0000 






: J: 




373 


0207 


( 


374 


0411 


( 


375 


0000 




376 


2400 




1778 


0000 





*'r/Mj " 



NAME OF ENTRY IS"I0H ' 



LOAD POINTER F0R"I0H" 



NAME OF ENTRY IS" EXIT.." 



LOAD POINTER F0R"EXIT" 



) MARKS END OF ENTRIES 



(RELATIVE BLOCK lOsKONE PAGE LONG) 
(RELATIVE BLOCK 128XTW0 PAGES LONG) 

(RELATIVE BLOCK 1)( 123 PAGES LONG) 
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APPENDIX B 



DETAILED LAYOUT OF THE SYSTEM 



This appendix covers three topics: the reserved areas on the 
system device, the resident portion of PS/8, and the various 
system tables. 

B.l Layout of the System Device 

The first 70o blocks (14K words) on the system device are re- 

o 

served by the PS/8 system. These blocks are used as follows: 

Block (s) in Octal Contents 

System Bootstrap Routine 

Device Directory 

Keyboard Monitor 

User Service Routine 

Device Handlers 

ENTER Processor for USR 

System Scratch Blocks 

Command Decoder 

SAVE and DATE Overlays 

Monitor Error Routine 

CHAIN Processor for USR 

System ODT 

Reserved for System Expansion 

File storage begins with block 70g. 

The system scratch blocks are used for preserving the contents 
of core when the Keyboard Monitor, USRy Command Decoder, or ODT 
are loaded. In addition, various system programs use the scratch 
area. Most importantly , the SAVE command expects the Core Control 
Block to be loaded in words 200g to 377g of block 37g. The Core 
Control Block is stored at those locations by the GET or RUN com- 
mand or by the ABSLDR or LOADER program. 

A detailed breakdown of system scratch block usage follows: 
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pr 




i-e 


1 


7-12 


13- 


-15 


16- 


•25 


26 




27- 


■50 


51- 


•53 


54- 


-55 


56 




57 




6 0- 


-63 


64- 


-67 



Block (s) in Octal 
27-32 

33-36 

37 



40-47 
50 



Contents 

The contents of locations 10000 to 11777 
are saved in this area when the USR is 
loaded. 

The contents of locations to 1777 are 
saved in this area when the Command De- 
coder, Keyboard Monitor, or ODT is loaded, 

Words 200g to 377g of this block contain 
the Core Control Block for the last pro- 
gram loaded by the GET or RUN command, or 
the ABSLDR or LOADER program. 

Used as scratch storage by the ABSLDR and 
LOADER programs. 

Reserved for future expansion. 



B.2 Layout of the PS/8 Resident Program 

The top core pages in fields and 1 are used by the resident por- 
tion of PS/8 and are not accessible by the user. Future expansion 
of PS/8 may later require space to be allocated in the top page 
of field 2. As a general rule, system and user programs should 
never destroy the contents of locations 7600 to 7777 of aii^ 
field. 



The resident portion of PS/8 is structured as foil 



ows 



Loca- 
tion Contents 




Notes 


7600 


WRITE OPERATION 


— NON-DESTRUCTIVE 
ENTRY TO PS/e 


7605 


JMP TO FIELD 1 FOR READ ■♦ 


DESTRUCTIVE 
ENTRY TO PS/8 


7607 

< 

7743 


: SYSTEM DEVICE HANDLER : 


r^ENTRY TO SYSTEM 
DEVICE HANDLER 


7744 
7745 


CURRENT STARTING ADDRESS 




7746 


JOB STATUS WORD 




7747 


■♦ 


— MUST ALWAYS BE ZE 


7750 
7755 


RESERVED FOR DATA BREAK 
LOCATIONS 




7756 
7777 


! PROGRAM SETUP AREA 


S 


— THE KEY BOARD 
1 MONITOR AND ODT 
MODIFY THIS AREA 
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TOP PAGE OF FIELD 1 



Loca- 
tion 



Contents 



Notes 



7600 



, ■' OUTPUT FILE LIST (3 ENTRIES) 



7616 
7617 



7641 
7642 
7643 

7645 
7646 
7647 

7665 
7666 
7667 



7677 
7700 



7740 
7741 



7757 
7760 

7776 
7777 



INPUT FILE LIST 
(MAXIMUM 9 ENTRIES) 

e 



HIGH 11 BITS 0F = N 



SPECIFIED OPTIONS 



LOW 12 BITS OF =N 



DEVICE HANDLER 
RESIDENCY TABLE 



SYSTEM DATE WORD 



READ OPERATION 

(LOAD KEYBOARD MONITOR) 



USR CALL AND RETURN AREA 



USER DEVICE 
NAME TABLE 



A 



DEVICE CONTROL WORD TABLE 



UNUSED 



^ 



-0 MARKS END 
OF LIST 

-* BIT = 1 IF 
COMMAND LINE 
TERMINATED BY 
ALTMODE 



COMMAND 

DECODER 

AREA 



K 



ENTRY TO USR 

NOTE 
-SYSTEM ODT DESTROYS 
CONTENTS OF THIS TABLE 
WHEN SETTING BREAKPOINTS 



RESERVED FOR FUTURE USE 



B.3 System Device Tables 

Each device is described to the system by entries in five sys- 
tem tables. Each of these tables is fifteen words long, where 
the device number is the index into the table. The five tables 
are described below. 

B.3.1 Permanent Device Name Table 

Entries in this table specify the permanent name of each device. 
The entries are computed by encoding the actual four-character 
device name in a single word as follows : 
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a. The device name is expressed as two words in 
the standard DEVICE format. For example, if 
the device name were "PTR" , the two words would 
be: 

WORD 1: 2024 
WORD 2: 2200 

Note that when the device name is left justified; 
O's are inserted to fill four characters. 

b. A single word is created by adding together these 
two words . 

c. If word 2 is non-zero, bit of the resulting word 
is forced to be a one. For example, the table 
entry for "PTR" would be 4224. 



An entry of zero means that there is no device for the corre- 
sponding device number. 



NOTE 

Conventionally, device names consist only of the 
characters A to Z and to 9. The first charac- 
ter of the device name should be alphabetic. The 
coding used makes all one and two character device 
names unique; however, names of more than two 
characters are not unique. For example, "PTR" 
and "RTP" have the same encoding. 



The Permanent Device Name Table is fifteen locations long; it 
resides in the USR. When the USR is in core the beginning of 
the table is in field 1 at a location the address of which is 
contained in location 10 03 6. 

B.3.2 User Device Name Table 

Entries are made in this table whenever the user performs cin 
ASSIGN and are restored to zero by a DEASSIGN. These entries 
have the same format as those in the Permanent Device Name 
Table. 

The User Device Name Table resides in locations 17741 through 
17757. 
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NOTE 

The User Device Name Table is used by ODT for 
setting breakpoints. For this reason the user 
should never ASSIGN any user device names when 
debugging with ODT. 

B.3.3 Device Handler Residency Table 

When a device handler is loaded by the USR, the entry in this 
table for the device loaded (and entries for all devices whose 
handlers are co-resident, if any) is set to contain the entry 
point for the device handler. Entries other than those that 
contain an address above 7600 (thus referring to the system 
handler) are restored to when a RESET, DECODE or CHAIN function 
is executed. When a program exits to the Keyboard Monitor this 
table is not cleared. The Keyboard Monitor Commands GET, RUN, 
R, SAVE, and START (with no explicit address) clear this table. 

NOTE 

Since the system device handler is always resi- 
dent, the first entry (since SYS is always de- 
vice number 1) in the Device Handler Residency 
Table is always 7607 (the entry point of the 
system device handler) . 

The Device Handler Residency Table resides in locations 17647 
through 17665. 

B.3.4 Device Handler Information Table 

Each entry in this table contains all the information needed by 
the USR to load the corresponding handler. The format of these 
entries is as follows : 
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Bit Condition 

Bit 0=1 
Bits 1 to 4 



Bits 5 to 11 



Mean ing 

If this is a two page device handler. 

Contain the relative block location of 
the device handler record on the system 
device. This is computed by subtracting 
15 octal (one less than thei first device 
handler block) jrom the actual block numlser. 

Contain the offset of the handler entry 
point from the beginning of the page. 
Note that two page device handlers must 
have their entry points in the first page. 



If an entry is the corresponding device handler is not saved 
in any of the device handler storage blocks. This is always 
true of device number 1 (the system device) and for all device 
numbers that are not used in a given configuration. The Device 
Handler Information Table is 15 locations long and resides in 
the USR. When the USR is in core the beginning of the table is 
in field 1 at a location the address of which is contained in 
location 10037. 

B.3.5 Device Control Word Table 



Entries in this table specify special device characteristics, 
including the physical device type. The entry format is as 
follows: 

Meaning 

If the device is file-structured. 

If the device is read-only. 

If the device is write-only. 



Bit Condition 



Bit 0=1 
Bit 1=1 
Bit 2=1 
Bits 3 to 8 



Contain the physical device type 
code (described below). 
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Bit Condition Meaning 

Bits 9 to 11 For file structured devices, these bits 

contain the directory block number of 
the currently active tentative file. 
If bits 9 to 11 are zero, there is no 
active tentative file on the device. 
For non-file structured devices, bits 
9 to 11 are always zero. Bits 9 to 11 
are reset to zero by the commands GET, 
RUN, R, SAVE, START (with no explicit 
address) and optionally by the USR func- 
tions RESET and DECODE. 

The device type is a number between and 77 „, of which 

o 

through 20g are currently assigned to existing devices, as 
follows : 



Device Type 




Code 


Device 





Teletype 


1 


High-speed paper tape reader 


2 


High-speed paper tape punch 


3 


Card Reader 


4 


Line Printer 


5 


RK8 Disk 


6 


256K Disk (RFj2f8) 


7 


512K Disk (RF|af8 + RSi2f8) 


10 


76 8K Disk CRF0Q + 2 RS08"s) 


11 


1024K Disk (RF08 + 3 RS/2f8's) 


12 


32K Disk (DF32) 


13 


64K Disk (DF32 + DS32) 


14 


96K Disk (DF32 + 2 DS32's) 


15 


128K Disk (DF32 + 3 DS32's) 


16 


DECtape 


17 


LINCtape (PDP-12 only) 


20 


Magnetic Tape 


21-77 


To be assigned 



The Device Control Word Table resides in locations 17760 
through 1777 6. 

B.3.6 Device Length Table 

There is a sixth table that is not normally considered part 
of the system tables. This is the Device Length Table and 

is used only by PIP to perform the /Z (zero directory) and /S 
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Ccompress device) options. This table is 64 locations long,, 
one entry for each possible physical device type. In this 
table an entry of means that the corresponding device is 
non-file structured; otherwise the entry contains the negative 
of the number of available 256-word blocks on the device. 

For example, the entry for a 256K disk would be 6000g (minus 
2000 , or 1024^Q, 256-word blocks). 

The Device Length Table resides in PIP. When PIP is brought 
into core the Device Length Table is in locations 13600 to 
13677. When new device types are added to the system this 
table should be patched with ODT to reflect the device length 
of the new device. 
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APPENDIX C 



SYSTEM ERROR CONDITIONS AND MESSAGES 



This is a summary of all error messages that are a result of 
system errors. These errors are also described in the rele- 
vant sections of this manual and in the 8K Programming System 
User's Guide. 

C.l System Halts 

Errors that occur as a result of a major I/O failure on the 
system device can cause a system halt to occur. These are as 
follows : 

Value of PC Meaning 

00601 A read error occurred while attempting to load 

ODT. Return to the Keyboard Monitor by restart- 
ing at 07605. 

07461 An error occurred while reading a program into 
core during a CHAIN. Return to the Keyboard 
Monitor by restarting at 07605. 

07605 An error occurred while attempting to write the 
Keyboard Monitor area onto the system scratch 
blocks. Verify that the system device is not 
WRITE LOCKED and restart at location 07600 to 
try again. 

07702 A user program has performed a JMS to 7700 in 
field 0. This is a result of trying to call 
the USR without first performing a GIF 10. As 
location 07700 has been destroyed, the user must 
re-bootstrap the system! 

07764 A read error occurred while loading a program. 
Return to the Keyboard Monitor by restarting at 
07605. 

07772 A read error occurred on the system scratch area 
while loading a program. Return to the Keyboard 
Monitor by restarting at 07605. 
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Value of PC Meaning 

10066 An input error occurred while attempting to 

restore the USR. Return to the Keyboard Moni- 
tor by restarting at 7605. 

10256 A read error occurred while attempting to load 
the Monitor Error routine. Return to the Key- 
board Monitor by restarting at 07605. 

176 76 An error occurred while attempting to read the 
Keyboard Monitor from the system device. Try 
again by restarting at location 07605. DO NOT 
PRESS CONTINUE. 

17721 An error occurred while saving the USR area. 
Verify that the system device is not WRITE 
LOCKED, and press CONTINUE to try again. 

17727 An error occurred while attempting to read the 
USR from the system device. Return to the Key- 
board Monitor by restarting at 7605. 

17736 An error occurred while reading the scratch 
blocks to restore the USR area. Return to 
the Keyboard Monitor by restarting at 07605,, 

Also, there is one halt in the LOADER program: 

00005 A parity error occurred when attempting to 
overlay the LOADER from the system scratch 
blocks. Return to the Keyboard Monitor by 
restarting at 07605, and try again. 

After retrying the operation which caused the failure, if the 
error persists it is the result of a hardware malfunction or a 
parity error in the system area. Run the appropriate diagnostic 
program to check the device and rebuild the system. 

C. 2 USR Errors 

Fatal errors that occur during operation of the USR cause the 
message: 

MONITOR ERROR n AT xxxxx 

to be printed. In these cases, the value "n" describes the 
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error and "xxxxx" is the address of the call to the USR that 
caused the error. The six Monitor errors are: 



Message 
MONITOR ERROR 1 AT xxxxx 

MONITOR ERROR 2 AT xxxxx 



MONITOR ERROR 3 AT xxxxx 



MONITOR ERROR 4 AT xxxxx 



MONITOR ERROR 5 AT XXXXX 



MONITOR ERROR 6 AT xxxxx 



Meaning 

File length in CLOSE function is 
too large. 

An I/O error occurred while at- 
tempting to read or write a direc- 
tory block. This is generally 
caused by the device being WRITE 
LOCKED . 

The device handler required for 
a file operation (LOOKUP, ENTER, 
CLOSE) is not in core. 

Illegal call to the USR; either 
an attempt has been made to call 
the USR from locations 10000 to 
11777 or a device number of zero 
was specified. 

I/O error occurred while reading 
or writing on the system device. 
Verify that the system device is 
not WRITE LOCKED. 

Directory overflow occurred (see 
section A. 1.2 for limitations on 
number of directory entries) . 



In addition to the MONITOR ERROR messages, system and user pro- 
grams can use the USR to print: 

USER ERROR n AT xxxxx 

by using the ERROR function. In this case the value of "n" is 
user-defined and "xxxxx" is the address of the call to the USR. 

Currently, two USER ERROR numbers have been assigned: 



Message 
USER ERROR (ji AT xxxxx 



Meaning 

An I/O error occurred while at- 
tempting to load a program with 
the GET, RUN, or R command. 
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Message 
USER ERROR 1 AT xxxxx 



Meaning 

While running a FORTRAN or SABR 
program, an attempt was made to 
call a subroutine that had not 
been loaded. 



Following either a MONITOR ERROR message or a USER ERROR message 
the USR exits to the Keyboard Monitor; the current contents of 
core are preserved and bit 2 of the Job Status Word is set to 
a 1 to prevent continuing from the error. 

C.3 Keyboard Monitor Errors 

In addition to the USR errors described previously, the follow- 
ing errors can occur after a command is given to the Keyboard 
Monitor: 



Message 



aaaa; 



TOO FEW ARCS 



device NOT AVAILABLE 



name NOT FOUND 



BAD ARCS 

ILLEGAL ARC. 
SAVE ERROR 



Meaning 

The Keyboard Monitor cannot inter- 
pret the command "aaaa" . For ex- 
ample, if the user types HELLO, 
the system will respond HELLO? 

An argiament has been omitted from 
a command. 

The permanent device name specified 
in an ASSIGN, SAVE, RUN, or GET com- 
mand does not exist. 

The file name specified was not 
located on the device indicated. 
This error can also be caused by 
trying to RUN or GET from an output 
only device. 

Arguments to a SAVE command are in- 
consistent. 

Illegal syntax in a SAVE command. 

An I/O error occurred while saving 
the program. The contents of core 
remain intact. 
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Message 
BAD CORE IMAGE 

NO! ! 



BAD DATE 



SYSTEM ERROR 



Meaning 

The file requested with an R, 
RUN, or GET command is not a 
core image file. 

A START command (with no address 
specified) is prohibited when 
bit 2 of the Job Status Word 
(location 07746) is a 1. 

Improper syntax in a DATE com- 
mand. 

An error occurred while doing 
I/O to the system device. 



C.4 Command Decoder Errors 

The following errors are printed by the Command Decoder. After 
the error message, the Command Decoder starts a new line, prints 
a *, and waits for another command line. The erroneous command 
is ignored. 



Message 
ILLEGAL SYNTAX 

TOO MANY FILES 

device DOES NOT EXIST 



name NOT FOUND 



Meaning 

The command line is formatted in- 
correctly. 

More than three output files or 
nine input files were specified.* 

The specified device name does 
not correspond to any permanent 
device name or any user assigned 
device name. 

The specified input file name was 
not found on the device indicated, 



*In the special mode of the Command Decoder this message would 
be printed if more than one output file or five input files 
were specified. See section 3.5. 
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APPENDIX D 



PROGRAMMING NOTES 



This appendix is a potpourri of ideas and techniques 
that have proven useful in programming the PDP-8. 
PS/8 users may find some use in their own programs 
for the techniques mentioned here. 



D.l The Default File Storage Device, DSK 

D.2 Modification to Card Reader Handler 

D.3 Suppression of Carriage Return/Line Feed in FORTRAN I/O 

D.4 Accessing the System Date in a FORTRAN Program 

D.5 Determining Core Size on PDP-8 Family Computers 

D.6 Relocating Code 

D.7 Using PRTC12-F to Convert PS/8 DECtapes to PS/12 LINCtapes 

D.8 Notes on Loading Device Handlers 

D.9 Available Locations in the USR Area 

D.IO Accessing Additional Information Words in PS/8 

D.ll SABR Programming Notes 
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D.l The Default File Storage Device, DSK 

The Command Decoder, as noted earlier, makes certain assumptions 
about the I/O device where none is explicitly stated. Namely, 
on all output files where no device name is given, the device 
DSK is assumed. On the first input file where no device name is 
given, DSK is assumed. Subsequent input files assume the same 
device as the previous input file. This convention was adopted 
to simplify typing command lines. 

The permanent device name DSK is assigned when the system is 
built. On all standard systems, DSK is equivalent to SYS. Chang- 
ing the default file storage device is described in Chapter 5. A 
useful technique is to use the ASSIGN command to redefine the 
meaning of DSK temporarily. For example, where device DTA|2f is 
equivalent to DSK and it becomes desirable to change DSK to DTAl, 
the following command can be given: 

.ASSIGN DTAl DSK 

DTAl remains the default file storage device until it is assigned 
a new name or a DEASSIGN command is executed. This technique is 
considerably easier to use than rebuilding the entire system. 

D.2 Modification to Card Reader Handler 

The standard card reader handler for PS/8 uses the DECj?29 standcird 
card codes. Some installations may prefer to use the DECi^ae codes 
instead. This can be done by changing the card conversion table 
in CONFIG, reassembling CONFIG, and rebuilding the system, or by 
rebuilding the system using the following procedure: 

a. Follow steps 1, 2, and 3 given in section 8.2 of the 
8K Programming System User's Guide (if building a 
DECtape system, mount the tape on which the system 
is to be built on unit ffS, WRITE ENABLEd, and load 
the DECtape CONFIG binary tape in step 3) . 
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b. Make the following patch: 
CHANGE LOCATION FROM TO 

5704 
5705 
5706 

5714 
5715 
5716 

5724 
5725 
5726 
5727 

5734 
5735 
5736 

c. Now continue building the system with step 4 of 
section 8.2 in the 8K Programming System User's 
Guide. The new system will have modified card 
codes. 

NOTE 

This procedure does not affect FORTRAN 
run time card input with READ (3,n) . The 
conversion table for FORTRAN is 
UTILTY.SB on source DECtape #3. 



3203 


7735 


4007 


4076 


3502 


0774 


7514 


3314 


0577 


1002 


3637 


0305 


0104 


3204 


1211 


1273 


3374 


3606 


0641 


1341 


7316 


3716 


3410 


1175 


1376 


3401 
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026 PUNCH CARD CODES 



Octal 8-bit 


DECJ2(2 6 




Octal 8-bit 


DEC026 




Code 


Code 
blank 


Character 
SPACE 


Code 


Code 
8-4 


Character 


240 


300 


§ 


241 


12-8-7 


1 


301 


12-1 


A 


242 


0-8-5 


" 


302 


12-2 


B 


243 


0-8-6 


# 


303 


12-3 


C 


244 


11-8-3 


$ 


304 


12-4 


D 


245 


0-8-7 


% 


305 


12-5 


E 


246 


11-8-7 


& 


306 


12-6 


F 


247 


8-6 


I 


307 


12-7 


G 


250 


0-8-4 


( 


310 


12-8 


H 


251 


12-8-4^ 


) 


311 


12-9 


I 


252 


11-8-4 


* 


312 


11-1 


J 


253 


12 


+ 


313 


11-2 


K 


254 


0-8-3 


f 


314 


11-3 


L 


255 


11 


- 


315 


11-4 


.M 


256 


12-8-3 


• 


316 


11-5 


N 


257 


0-1 


/ 


317 


11-6 





260 








320 


11-7 


P 


261 


1 


1 


321 


11-8 


Q 


262 


2 


2 


322 


11-9 


R 


263 


3 


3 


323 


0-2 


S 


264 


4 


4 


324 


0-3 


T 


265 


5 


5 


325 


0-4 


U' 


266 


6 


6 


326 


0-5 


V 


267 


7 


7 


327 


0-6 


w 


270 


8 


8 


330 


0-7 


X 


271 


9 


9 


331 


0-8 


^ 


272 


11-8-2 


• 


332 


0-9 


z 


273 


0-8-2 


• 


333 


11-8-5 


[ 


274 


12-8-6 


< 


334 


8-7 


\ 


275 


8-3 


= 


335 


12-8-5 


] 


276 


11-8-6 


> 


336 


8-5 


/v. 


277 


12-8-2 


? 


337 


8-2^ 





On some IBM 026 Keyboards this character is graphically repre- 
sented as n . 

2 

A card containing an 8-2 in column 1 with all remaining columns 
blank is an end-of-file card. 
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D.3 Suppression of Carriage Return/Line Feed in FORTRAN 

It is often desirable to suppress the automatic carriage return/ 
line feed (CR/LF) following FORTRAN WRITE statements to achieve 
an easily readable text. The following three methods in PS/8 
FORTRAN can be used to achieve this result: 

a. Follow the I/O, list of a WRITE statement with a 
comma. Thus, the following statements: 

WRITE Cl,li2f)2f) N, 
100 FORMAT (1X,15HTHE VALUE OF A(,I2,5H) IS ) 

READ (1,1^2(1) A(N) 
lj2fl FORMAT CF8.4) 

result in the following single line (assume N has 
a value of 12 and a value of 147.83 is being input): 

THE VALUE OF A (12) I S 147.83 

b. Use of an empty field print statement enables a text 
to be printed without a following CR/LF when there 
is no variable to be printed. For example: 

WRITE (l,lJ3f2) I DUMMY, 
lj?2 FORMAT ('DESIRED TEXT" ,I|af) 

c. READ statement using break character, as follows: 

READ (l,lj2fl) IA,IB,IC 
lj2fl FORMAT ('A=' ,11, '6=' ,11, 'C=' ,11) 

results in no CR/LF after each phrase is printed. 
That is, the output is all printed on a single line. 
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D.4 Accessing the System Date in a FORTRAN Program 

The availability of the system Date word in location 17666 is 
useful to many PS/8 programs. The following FORTRAN program 
illustrates how the Date can be accessed in SABR code: 



C PROGRAM PRINTS THE CURRENT DATE 

C 

S DUMMY DATE 

S TAD I DATE 

S DCA TEMP 

S TAD TEMP 

S AND C7 

S DCA \ lYR 

S TAD TEMP 

S RAR;RTR 

S AND (37 

S DCA \IDAY 

S TAD TEMP 

S CLL RAL;RTL;RTL 

S AND C17 

S DCA \IM0 

WRITE Cl,l|?|?) IMO,IDAY,IYR 

10fi FORMAT (/'DATE: ' 12 ' - ' 12 ' -197 " 11/) 

CALL EXIT 

S CPAGE 2 

SDATE, 6211 

S 7666 

STEMP , )2f 
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D.5 Determining Core Size on PDP-8 Family Computers 

Many times system programs need to determine the amount of core 
available to them at run time. For example, the PS/8 system 
programs LOADER, PALS, and CREF perform this calculation. Be- 
cause of differences in the extended memory control of PDP-8 
family computers, subroutines that work on one machine might not 
work on another . 

The following three conditions cause the most difficulty: 

a. On a PDP-8 with an extended memory control, address- 
ing nonexistent memory from field J? causes the 
following instruction to be skipped and the contents 
of the corresponding field |? location to be executed. 
For example: 

CDF 70 /NONEXISTENT FIELD 

TAD I CX) /EXECUTED LOCATION X 

HLT /THIS INSTRUCTION SKIPPED 



X, CLA CLL CML RAR /LOAD 4000 

the preceding code causes 4000 to be loaded into 
the AC and the HLT instruction to be skipped when 
executed on a PDP-8. 

b. On a PDP-12 with an odd number of 4K banks (12K, 
20K, 2 8K) , all reads in the first nonexistent field 
load zeros. Reads to higher fields, as well as all 
reads to nonexistent memory on a machine with an 
even number of 4K banks load all one bits. 

c. The PDP-8/L normally treats all CDF's to fields 2 
through 7 as NOP ' s . (It tests bits 6 and 7 of all 
CDF and CIF instructions for 0's before executing 
the lOT.) However, there is a special 12K option 
for the PDP-8/L called a BMJ38. With this option 

a CDF to field 2 is valid, but a CDF to field 3 re- 
sets the Data Field to 0. CDF's to fields 4 
through 7 remain NOP ' s . 

For those who are interested, the following subroutine has been 
tested on the PDP-8, 8/S , 8/L, 8/1, 8/E, PDP-12, and LINC-8 com- 
puters. For the purpose of this example, it is assembled at 
00200. This is not essential, it can be in any 40 (octal) 
locations of any page in field 0. 
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/SUBROUTINE TO DETERMINE CORE SIZE. 

/THIS SUBROUTINE WORKS ON ANY PDF- 8 FAMILY 
/COMPUTER. THE VALUE, FROM 1 TO IJ? (OCTAL), 
/OF THE FIRST NON-EXISTENT MEMORY FIELD IS 
/RETURNED IN THE AC. 

/NOTE — THIS ROUTINE MUST BE PLACED IN FIELD ^ 



J?2J2fJ2f 


0000 


CORE, 









i2f2j?l 


7300 




CLA 


CLL 




J?2i2f2 


6201 


COR0, 


CDF 







J2(2j2f3 


1237 




TAD 




CORSIZ 


J?2|2(4 


7006 




RTL 






J2f2j2(5 


7004 




RAL 






J?2j2(6 


0217 




AND 




COR70 


02^1 


1232 




TAD 




COREX 


021J? 


3211 




DCA 




. + 1 


0211 


6201 


CORl, 


CDF 




/N 


J3f212 


1635 




TAD 


I 


CORLOC 


0213 


7000 


C0R2, 


NOP 






0214 


3211 




DCA 




CORl 


0215 


1213 




TAD 




C0R2 


0216 


3635 




DCA 


I 


CORLOC 


0217 


0070 


COR70, 


70 






0220 


1635 




TAD 


I 


CORLOC 


0221 


7400 


CORX, 


740J2 


f 




0222 


1221 




TAD 




CORX 


0223 


1236 




TAD 




CORV 


0224 


7640 




SZA 


CLA 




0225 


5232 




JMP 




COREX 


0226 


1211 




TAD 




CORl 


0227 


3635 




DCA 


I 


CORLOC 


0230 


2237 




ISZ 




CORSIZ 


0231 


5202 




JMP 




COR0 


0232 


62je}l 


CO REX, 


CDF 







0233 


1237 




TAD 




CORSIZ 


0234 


5600 




JMP 


I 


CORE 


0235 


0221 


CORLOC, 


CORX 




0236 


1400 


CORV , 


1400 




0237 


0001 


CORSIZ, 


1 







/{NEEDED FOR PDP-8L) 
/GET FIELD TO TEST 



/MASK USEFUL BITS 

/SET UP CDF TO FIELD 
/N IS FIELD TO TEST 
/SAVE CURRENT CONTENTS 
/(HACK FOR PDP-B:) 

/7000 IS A "GOOD" PATTE:E^ 

/(HACK FOR PDP-8. , NO-OP) 
/TRY TO READ BACK 7000 
/(HACK FOR PDP-8, .NO-OP) 
/GUARD AGAINST "WRAP AROUND" 
/TAD (1400) 

/NON-EXISTENT FIELD EXIT 
/RESTORE CONTENTS DESTROYED 

/TRY NEXT HIGHER FIELD 



/LEAVE WITH DATA FIELD 
/IST NON-EXISTENT FIELD 



/ADDRESS TO TEST IN EACH FIELD 
/7000+7400+1400 = 

/CURRENT FIELD TO TEST 
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D.6 Relocating Code 

One useful programming trick is generating relocated code by 
means of the ENPUNCH and NOPUNCH features of PALS. 

In this case, relocated code is code that, for some reason, is 
to be loaded into an area of core different from the area in 
which it is to be executed. For example, the system device handler 
for PS/8 is loaded into 6600 through 6777, so as not to affect 
the Binary Loader, and during the build process it is moved to the 
top page of field j3r where it resides. Of course, it cannot be 
simply assembled directly into 6600, since various address con- 
stants would be generated incorrectly. The way around this 
situation is to do two origins: the first to the location in 
which the code is loaded and the second to the location in which 
it is eventually executed . The second origin is preceded by 
a NOPUNCH so that no origin punch is put onto the binary output 
of PALS. 

For example, if some code were to be loaded into 12 77 through 1476 
but executed at 2000 through 2377, the following should appear 
in the source file preceding the code: 

*12 77 /ADDRESS TO LOAD 

NOPUNCH 

*2^00 /ADDRESS OF EXECUTION 

ENPUNCH 

/CODE BEGINS HERE 
*1477 /RESET ACTUAL ASSEMBLY ORIGIN 

This technique is used in several places in the source of PS/8. 

NOTE 

Code that is relocated in this fashion must not 
use current page literals as they will be loaded 
into the wrong area. In addition, current page 
literals should not be used in any code that 
immediately precedes the relocated code, and 
that is to be loaded onto the same page. 
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D.7 Using PRTC12-F to Convert PS/8 DECtapes to PS/12 LINCtapes 

Many users of PS/8 on the PDP-12 will be interested in the fact 
that, since PS/8 uses an identical file structure on all devices, 
PDP-8 DECtape in PS/8 format may be directly copied to PS/8 
LINCtapes by the PRTC12-F program. 

The PRTC12-F program uses the PDP-12 TC12-F hardware option to 
read DECtapes and convert these tapes to LINCtape. This hard- 
ware option is required to read DECtapes on the PDP-12. 

The PRTC12-F program is described in the document DEC-12-YIYA-D. 
This document describes the program operation in detail, and 
must be read before attempting to use PRTC12-F. The operations 
that convert PS/8 format DECtapes are as follows: 

a. Mount the PS/8 DECtape on unit 1 and a PDP-12 
LINCtape formatted with 129 words per block on 
unit 2. 

b. When the READ questionnaire is displayed, 
respond as follows (responses are underlined; 
the character ^ stands for carriage return 
and 4- stands for line feed) : 

READ 1777J BLOCKS 



TAPE FORMAT A J UNIT iJ 



STARTING WITH BLOCK ^J^ 
etc. 

c. When the WRITE questionnaire is displayed, respond 
as follows : 



WRITE THE RESULT 

IN TAPE FORMAT B ) ON UNIT 2j 

STARTING AT BLOCK j? J i 

etc. 
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D.8 Notes on Loading Device Handlers 

A. Problem with multiple input files 

There is a problem associated with reusing Device Handler areas 

in PS/8. This problem is best illustrated by an example: 

Assume a program has reserved locations 1000-1377 for its input 
handler and locations 7400-7577 for its output handler. If the 
program gives a USR FETCH command to load the DTAl handler as 
an input device handler, all 8 DECtape handlers will load into 
1000-1377, since they are all co-resident. If another FETCH is 
issued to load the DTA2 handler as an output device handler, 
that handler will not be loaded, because it shares space with 
the DTAl handler currently in core. This is fine — however, if 
the user now switches input devices and FETCHes the paper tape 
reader handler as an input device handler it will destroy the 
DTA2 handler and the next attempt to output using the DTA2 
handler will produce errors. There are two ways to get around 
this problem. 

1. Always assign the handler which you expect to 
stay in core the longest first. Most programs can 
process more than one input file per program step 
(e.g., an assembly pass is one program step) but 
only one output file; therefore, they assign the 
output handler before any of the input handlers . 
In the above example, the problem would be 
eliminated if the DTA2 handler were assigned 
first. 

2. Always give a USR RESET call before each FETCH. 
Obviously, this call should not delete any open 
output files. This means that the USR will always 
load the new handler, even if another copy is in 
core. The user must FETCH the output handler again 
before issuing the USR CLOSE call, otherwise the 
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USR will determine that the output handler is not 
in core and give a MONITOR ERROR 3 message. 

8K FORTRAN uses this second method for device-independent I/O 
at run time . 

B. Dynamically Loading Device Handlers 

Some programs which use dynamic core allocations will want to 
use PS/8 Device handlers but cannot afford to always allocate 
the maximum of two pages per handler. The following is a sub- 
routine which loads a device handler dynamically, returning its 
entry in the AC. It assumes that the name of the handler is in 
locations NAMEl and NAME2, and a subroutine GETPAG exists which 
gets a page from the bottom of available field j? of storage and 
returns its address in the AC. This example subroutine runs in 
field 1 and can only be called from field 1, but can be re- 
written for any other possibility. 

ASSIGN, J2f 

TAD NAMEl 

DCA Nl 

TAD NAME 2 

DCA N2 /MOVE DEVICE NAME INTO "INQUIRE" COMTdAND 

CDF CIF 10 

JMS I (7700 

10 /USRIN - FORCE USR INTO CORE 

JMS I (200 

12 /INQUIRE 

Nl, 
N2, J? 
LOCI, j2f 

JMP ASSERR /NO SUCH DEVICE - QUIT 

TAD LOCI 

SZA /IS THE HANDLER ALREADY IN CORE? 

JMP I ASSIGN /YES - RETURN ITS ENTRY POINT 

JMS GETPAG /GET A PAGE DYNAMICALLY 

DCA L0C2 
ASSTRY, TAD N2 /LOAD DEVICE NUMBER 

JMS I (200 

1 /FETCH 

L0C2, j3f /PAGE TO FETCH INTO 

JMP TWOPAG /FAILED - MUST BE A TWO-PAGE HANDLER 

TAD L0C2 

JMP I ASSIGN /RETURN ENTRY POINT 
TWOPAG, JMS GETPAG /GET ANOTHER PAGE 

ISZ L0C2 /SET "TWO PAGE HANDLER ALLOWED" BIT 

CLA 

JMP ASSTRY /FETCH WILL SUCCEED THIS TIME 
. ASSERR, /ERROR ROUTINE 
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D.9 Available Locations in the USR Area 

A few programs may need additional storage space in field 1 
when the USR is in core. A number of locations in the USR area 
ClOOOO to 11777) are available and may be used whenever the USR 
is in core. The locations are as follows: 

A. Locations 10000 to 10006 are available for scratch 
storage and/or ODT breakpoint usage, without restriction. 

B. All auto-index registers (locations 10010 to 10017) may be 
used, but these locations are destroyed by USR operations. 

C. Location 10020 to 10037 may be used as scratch storage 
with no restrictions. 

D. Locations 11400 to 11777 are used by the USR to preserve 
the last directory segment read while performing a LOOKUP, 
ENTER, or CLOSE operation. Location 10007 contains a key 
specifying which segment of which device is currently in 
core. 

Any user program may use locations 11400 to 11777 as 
scratch storage as long as location 10007 is set to 
before the first use. Of course, the LOOKUP, ENTER, and 
CLOSE operations will read a directory segment into 11400 
to 11777 and set 10007 to a non-zero value again. 
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D.IO Accessing Additional Information Words in PS/8 

In all of these cases, the USR must have been previously brought 
into core with the USRIN function. 

A. After a LOOKUP or ENTER 

After a LOOKUP or ENTER, location 10017 points to the length word 
of the file entry. To get a pointer to the first Additional 
Information Word, a program would execute the following code: 

CDF IjH 

TAD I C14j?4 /GET # OF ADDITIONAL INFORMATION WORDS 

/FROM DIRECTORY 

SNA 

JMP NONE /NO ADDITIONAL INFORMATION WORDS 

TAD I (J^l^l? 

DCA POINTER 



"POINTER" now points to the first Additional Information Word. 

B. After a CLOSE 

Because CLOSE is a legal operation even if no output file is 
present, it is not suggested that Additional Information Words 
be modified following a CLOSE. To alter the Additional Informa- 
tion Words of a permanent file, do a LOOKUP to get the directory 
segment into core, then alter the words and rewrite the directory 
segment. 

C. Rewriting the Current Directory Segment 

Whenever a user program changes the Additional Information Vfords, 
of a file, it must rewrite the directory segment containing that 
file entry in order to make sure the changes are permanently 
recorded. 

The following code, which must be in field 1, will rewrite the 
current directory segment: 
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SEGNO , 



CDF Ipf 
TAD 7 
AND (7 
DCA SEGNO 
GIF 
JMS I 51 
421J2f 
1400 

JMP ERROR 



/CODE IS IN FIELD 1 
/GET DIRECTORY KEY WORD 
/EXTRACT SEGMENT NUMBER 



/LOC 51 POINTS TO THE DEVICE HANDLER 

/WRITE OPERATION 

/DIRECTORY SEGMENT CORE ADDRESS 

/ERROR REWRITING DIRECTORY 



Location 10051 will always point to the device handler entry point 
used to read in the last directory segment, following a LOOKUP or 
ENTER operation. 
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D.ll SABR Programming Notes 

A. Optimizing SABR Code 

There are two types of users who will be using the SABR assembler - 
those who like the convenience of page-boundary-independent code 
and are willing to pay the price for it, and those who need a 
relocatable assembler but are still very location conscious. These 
optimizing hints are directed to the latter user. 

One way to beat the high cost of non-paged code is to Page It 
Yourself. This is done by using the LAP (Leave Automatic Paging) 
pseudo-op and the PAGE pseudo-op to force paging where needed. 
This saves 2 to 4 instructions per page from elimination of the 
page escape. In addition, the fact that the program must be 
properly segmented may save a considerable amount. 

Wasted core may be reduced by eliminating the ever-present CDF 
instructions which SABR inserts into a program. This is done by 
using "fake indirects". Define the following op codes: 

OPDEF ANDI |2f4J2fJ? 

OPDEF TADI 14^ fH 

OPDEF ISZI 24J?|? 

OPDEF DCAI 3 4j2fJ2f 



These codes correspond to the PDP-8 memory reference instructions 
but they include an indirect bit. The difference can best be 
appreciated by an example : 

If X is off-page, the sequence 

LABEL, SZA 

DCA X 

is assembled by SABR into 
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LABEL, SZA 

JMS 45 

SKP 

DCA I (X) 



or four instructions and one literal, 



The sequence 



FX, X 



LABEL, SZA 

DCAI PX 

assembles into three instructions for a saving of 40 percent. 
Note, however, that the user must be sure that the data field 
will be correct when the code at LABEL is encountered. Also 
note that the SABR assumes that the Data Field is equal to the 
Instruction Field after a JMS instruction, so subroutine returns 
should not use the JMPI op code. 

The standard method to fetch a scalar integer argument of a 
subroutine in SABR is: 



Code 



lARG, 


DUMMY X 







SUBR, 


BLOCK 2 




TAD I SUBR 




DCA X 




INC SUBR# 




TAD I SUBR 




DCA X# 




INC SUBR# 




TAD I X 




DCA lARG 



X, 



BLOCK 2 



This code requires 19 words of core and takes several hundred 
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microseconds to execute. The following sequence: 

Code 



lARG, 
SUBR, 



X, 



BLOCK 2 
TAD I SUBR 
DCA X 
INC SUBR# 
TADI SUBR# 
DCA lARG 
INC SUBR# 
HLT 

TAD I lARG 
DCA lARG 



/THIS IS A CDF 



takes only 14 words and executes in approximately 1/3 the time. 

B. Calling the USR and Device Handlers from SABR code 
One important thing to remember is that any code which calls the 
USR must not reside in locations 10000 to 11777. Therefore, any 
SABR routine which calls the USR must be loaded into a field 
other than field 1 or above location 2000 in field 1. To call 
the USR from SABR use the sequence: 



CPAGE n 

6212 

JMS 7 7^?^ 

REQUEST 

ARGUMENTS 

ERROR RETURN 



/N=7+(# OF ARGUMENTS) 

/CIF lJ2f 

/OR 2)2f0 IF USR IN CORE 

/OPTIONAL DEPENDING ON REQUEST 
/OPTIONAL DEPENDING ON REQUEST 



To call a device handler from SABR use the sequence; 



CPAGE 12 
62p(2 

JMS I HAND 
FUNCT 
ADDR 
BLOCK 

ERROR RETURN 
SKP 
HAND, J? 



/l)2f IF "HAND" IN PAGE j? 

/CIF 

/DO NOT USE JMS I 



/"HAND" MUST BE ON SAME PAGE 
/AS CALL, OR IN PAGE 01 [ 
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APPENDIX E 



CHARACTER CODES AND CONVENTIONS 



Table E-1 contains a list of the control characters used by 
PS/8 and associated system programs. Table E-2 contains 
the PS/8 character set, which is a subset of the complete 
ASCII code, the unlisted codes are generally not used by 
PS/8 or the system programs. Note the following: 

a. On some terminals, the character back- 
arrow {■<-) is replaced by an underline 
(_) character, and the up- arrow (+) is 
replaced by circumflex (^) . 

b. Some terminals use parity codes rather 
than forcing the leading bit of the 8- 
bit character code to be a 1. To avoid 
problems, PS/8 system programs always 
ignore the parity bit during ASCII input. 

c. PS/8 does not handle lower case charac- 
ters (octal codes 341 through 372) . 
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Table E-1 



PS/8 Control Characters 



Octal 
8-bit 
Code 



Character 
Name 



Remarks 



200 
2j2f3 



217 



225 



232 



null 

leader /trailer 

CTRL/C 



2J37 


BELL 


211 


TAB 


212 


LINE FEED 


213 


VT 


214 


FORM 


215 


RETURN 



CTRL/0 

CTRL/U 
CTRL/Z 



Ignored in ASCII input. 

Leader /trailer code precedes and 
follows the data portion of binary- 
files. 

PS/8 break character, forces re- 
turn to Keyboard Monitor, echoed 
as fC. 

CTRL/G. 

CTRL/I , horizontal tabulation. 

Used as a control character by 
the Command Decoder and ODT. 

CTRL/K, vertical tabulation. 

CTRL/L, form feed. 

Carriage return, generally echoed 
as carriage return followed by a 
line feed. 

Break Character, used conventionally 
to suppress Teletype output, echoed 
as to. 

Delete current input line, echoed 
as fU. 

End-of-File character for all ASCII 
and binary files (in relocatable 
binary files CTRL/Z is not a termi- 
nator if it occurs before the 
trailer code) . 
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Table E-1 



PS/8 Control Characters 



Octal 
8-bit 
Code 



Character 
Name 



Remarks 



233 
375 
376 
377 



ESC 



ALTMODE 



PREFIX 



RUBOUT 



Escape replaces ALTMODE on some termi- 
nals. Considered equivalent to ALTMODE, 

Special break character for Teletype 
input. 

PREFIX replaces ALTMODE on some termi- 
nals. Considered equivalent to ALTMODE, 

Key is labeled DELETE on some terminals, 
Deletes the previous character typed. 
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Table E-2 



ASCII Character Codes 



Octal 




Punched 


8-bit 


6-bit 


Card,^. 
Code^-^' 


Code 


Code 


24/3 


40 


blank 


241 


41 


11-8-2 


242 


42 


8-7 


243 


43 


8-3 


244 


44 


11-8-3 


245 


45 


0-8-4 


246 


46 


12 


247 


47 


8-5 


25)3 


50 


12-8-5 


251 


51 


11-8-5 


252 


52 


11-8-4 


253 


53 


12-8-6 


254 


54 


0-8-3 


255 


55 


11 


256 


56 


12-8-3 


257 


57 


0-1 


26(? 


60 





261 


61 


1 


262 


62 


2 


263 


63 


3 


264 


64 


4 


265 


65 


5 


266 


66 


6 


267 


67 


7 


270 


70 


8 


271 


71 


9 


272 


72 


8-2 


273 


73 


11-8-6 


274 


74 


12-8-4 


275 


75 


8-6 


276 


76 


0-8-6 


277 


77 


0-8-7 


300 


00 


8-4 


301 


01 


12-1 


302 


02 


12-2 


303 


03 


12-3 


304 


04 


12-4 


305 


05 


12-5 


306 


06 


12-6 


307 


07 


12-7 



Character 




Representa- 




tion 


Remarks 




space (non-printing) 


! 


exclamation point 


II 


quotation marks 
niimber sign (1^) 


# 


$ 


dollar sign 


% 


percent 


& 


ampersand 


1 


apostrophe or acute 




accent 



+ 



/ 




1 
2 
3 
4 
5 
6 
7 

8 
9 



> 



@ 
A 
B 
C 
D 
E- 
F 
G 



opening parenthesis 

closing parenthesis 

asterisk 

plus 

comma 

minus sign or hyphen 

period or decimal point 

slash 



colon 
semicolon 
less than 
equals 

greater than 
question mark 



at sign 
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Octal 
8-bit 
Code 



Table E-2 (Cont'd) 
ASCII Character Codes 



6-bit 
Code 



Punched 
Card 



Code 



(1) 



Character 
Representa- 
tion 



Remarks 



31j3 
311 
312 
313 
314 
315 
316 
317 



10 
11 
12 
13 
14 
15 
16 
17 



12-8 
12-9 
11-1 
11-2 
11-3 
11-4 
11-5 
11-6 



H 
I 
J 
K 
L 
M 
N 




320 
321 
322 
323 
324 
325 
326 
327 



20 
21 
22 
23 
24 
25 
26 
27 



11-7 
11-8 
11-9 
0-2 

0-4 
0-5 
0-6 



P 

Q 

R 
S 
T 
U 
V 
W 



330 
331 
332 
333 
334 
335 
336 
337 



30 
31 
32 
33 
34 
35 
36 
37 



0-7 
0-8 

^"^ (5) 
12-8-2;^' 

11-8-7^^^ 

0-8-2 , . 

12-8-7^/' 

0-8-5^-^' 



X 
Y 

Z 

[ 
\ 

] 



opening bracket, SHIFT/K 
backslash, SHIFT/l(8) 
closing bracket, SHIFT/M 
circumflex (?) „> 
underline ' 



Footnotes : 

(1) These are the DEC029 standard card codes. 

(2) On most DEC Teletypes circumflex is replaced by up-arrow (t). 

(3) A card containing 0-8-5 in column 1 with all remaining columns 
blank is an end-of-file card. 

(4) On most DEC Teletypes underline is replaced by backarrow ("*") • 

(5) On some IBM 029 keyboards this character is graphically repre- 
sented as a cent sign (*). 

(6) On some IBM 029 keyboards this character is graphically repre- 
sented as logical NOT (-.) . 

(7) On some IBM 029 keyboards this character is graphically repre- 
sented as vertical bar (| ) . 

(8) On a very few LP08 line printers, the character diamond ( o ) 
is printed instead of backslash. 

(9) On a very few LP08 line printers, the character heart ( o ) is 
printed instead of underline. 

(10) The character number sign on some terminals is replaced by 
pound sign ( £ ) . 
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APPENDIX F 

DOCUMENTATION UPDATE FOR THE 
8K PROGRAMMING SYSTEM USER'S GUIDE 



This appendix contains two sections on new PS/8 system pro- 
grams: PS/8 CREF, a cross reference listing program, and 
LIB SET, a new program for building a library of FORTRAN sub- 
routines . 

F.l CREF, Cross-Reference Program (DEC-P8-YRXA-PB) 

CREF is a PS/8 program which aids the programmer in writing, 
debugging and maintaining assembly language programs. CREF 
provides the ability to pinpoint all references to a parti- 
cular symbol in assembly language programs. CREF operates on 
output from either the PALS or SABR assemblers. 

F.1.1 Loading, Calling, and Using CREF 

In order to- load CREF, place the CREF binary tape (DEC-P8- 
YRXA-PB) into the reader and load as follows: 

.R ABSLDR 
*PTR:/9$ 

where the $ character indicates typing of the ALT MODE key. 
When the f character is printed, type any keyboard character 
to initiate reading the paper tape. When reading is completed. 
Keyboard Monitor responds with another dot. Type: 

-SAVE SYS: CREF 

and CREF is saved on the system device. 
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To call CREF from the system device, type: 

•R CREF 

where the . is the Keyboard Monitor active signal. The Com- 
mand Decoder is then loaded and replies with a star at the 
left margin. The user then enters one output file specifica- 
tion and one input file specification. 

NOTE 

The input to CREF must be the listing pass 
output from either assembler. If this is 
not the case, CREF will not operate proper- 
ly. 

If no output file is specified, CREF assumes the output is to 
be sent to the line printer. If no input file extension is 
specified, the extension .LS is assumed. If no input speci- 
fication is given, control returns to the Command Decoder un- 
til an input file is specified. 

An example of calling CREF is shown below: 

.R CREF 
*PTEMP 

The Command Decoder prints *, CREF assigns LPT: as the output 
device. The input file is DSK:PTEMP.LS. If the file PTENIP.LS 
is not found, a search for DSK:PTEMP is attempted. 

No output file extensions are appended. Options which can be 
specified to CREF are described in Table F-1. 

TABLE F-1 

CREF OPTIONS 

Option Code Meaning 

/X Do not process literals. For programs with too 

many symbols and literals for CREF, this option 
may create enough space for CREF to operate. 
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Option Code Meaning 

/R Interpret input as SABR code. Signal to CREF 
to accept special SABR characters. Also, if 
R is used, /X is forced on. 

/P Disables pass one listing output. The output 
is re-enabled when $ (or END if SABR code) is 
encountered. Thus the $ (END) and symbol table 
are printed if /P is used. 

Examples of calling CREF are shown below. 



.R CREF 
*SBRLS/R 

The line to the Command Decoder causes output to be sent to the 
line printer. The input is expected to be a SABR listing file 
named SBRLS.LS or SBRLS from device DSK:. 

.R CREF 

*DTA1:LIST< DTA3 :PALIST/X 

The above line to the Command Decoder causes output to be sent 
to DECtape unit 1, to a file named LIST. Input is expected to 
be a PALS listing file called PALIST.LS or PALIST. No literals 
appear in the CREF output table. 

F.1.2 Interpreting CREF Output 

The output from CREF consists of two parts. On the first pass 
through the input file, CREF generates a sequence numbered list- 
ing of the file. The sequence numbers are decimal. /P disables 
this part of the output. 

Following the listing, the cross reference table appears. This 
table contains every user defined symbol and literal sorted 
alphabetically. For each symbol, there appears a list of num- 
bers specifying the lines in which that symbol is referenced. 
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If CREF finds too many references to fit in core at one time, 
multiple passes are required to process all symbols. The mini- 
mum number of passes is two. The maximum depends on two things: 

a. Size of the input file, and 

b. Amount of core available 

CREF calculates the number of core fields available and uses 
all available space for reference tables. If enough core is 
not available, three or more passes are required. 

For example, the current PS/8 SABR assembler (5518 source lines, 
849 symbols) requires a total of four passes through CREF on 
an 8K machine. 



/EXAMPLE CREF OUTPUT 



PAL8-V6 



PAGE 1 



1 






/EXAMPI 


jE CREF out: 


2 




0200 




*200 


3 

4 
5 






/THIS IS WHAT TYP; 


0200 


1211 




TAD Al 


6 


)2f2/2ll 


3212 




DCA COUNT 


7 


|2f2)2(2 


7001 




lAC 


8 


02/2(3 


7104 




CLL RAL 


9 


0204 


2212 




ISZ COUNT 


10 


J2f205 


5203 




JMP .-2 


11 


J2f2j3f6 


3213 




DCA F2 


12 


J0207 


1377 




TAD (7777 


13 


i2(21i2f 


7402 




HLT 


14 


0211 


7400 


Al, 


-400 


15 


j2(212 


0000 


COUNT, 





16 


0213 


0000 


F2, 





17 


0377 


7777 






18 






$ 
(FORM 


FEED) 



/SET COUNTER 



/EXAMPLE CREF OUTPUT 
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PAGE 1-1 



Al 


0211 






COUNT 


0212 






F2 


0213 






19 






(FORM FEED) 


Al 




5 


14# 


COUNT 




6 


9 15# 


F2 




11 


16# 


L0377 




12 
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Form feeds on the Teletype are converted to a series of carriage 
return/line feeds and a dotted tear line. Notice that in the 
CREF table the line where the symlsol is defined is followed by 
a #. Symbols defined by OPDEF or SKPDF in SABR and all literals 
do not have a # following them. 

F.1.3 CREF Pseudo-Ops 

CREF recognizes the pseudo-ops of the assembler whose output it 
is processing. Certain pseudo-ops cause CREF to perform actions 
similar to those taken by the assembler. 



PAL8 Pseudo-Op 
EXPUNGE 



FIXTAB 



TEXT 

$ 
SABR Pseudo-Op 
END 
OPDEF 

SKPDF 



TEXT 



Action Taken by CREF 

CREF purges its current symbol table of all 
permanent and user defined symbols. If any 
literals were in the table they are not de- 
leted. 

Causes all symbols (except literals) to be 
marked as permanent symbols. After a FIXTAB, 
no references to previously defined symbols 
will be reported by CREF. 

Ignores characters between delimiters. 

End of input signal. 

A ction Taken by CREF 

End of input signal. 

Creates a new permanent symbol, a non-skip 
type instruction. 

Creates a new permanent symbol, a skip-type 
instruction. 

NOTE 

Symbols entered by OPDEF and SKPDF are 
processed by CREF. All references to 
these defined symbols are listed. How- 
ever, no reference is flagged as a defini- 
tion (i.e. , no reference is followed by 
a # in the CREF listing) . 

Ignore characters between delimiters. 
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F.1.4 Restrictions 



CREF has the following restrictions: 



a. Input format — CREF can only detect errors of a 
simple form (described below) . If the input is 
neither a PALS or SABR listing file, the results 
of CREF are unpredictable in the cross reference 
table. 

b. CREF can handle a maximum of 896 (decimal) symbols,, 
In 8K, PALS is limited to 89 7 symbols while SABR 

is limited to fewer than 800 symbols. If more than 
896 symbols are found, an error message is generated. 

c. If any symbol in the input file has more than 2044 
(decimal) references, an error message is generated. 

d. If more than 8192 (decimal) source lines are input, 
sequence numbers return to 4096, not 0. 

e. If the /X option is used in PALS (to generate a DDT 
compatible symbol table) and the output listing is 
put through CREF, no symbol table listing will ap- 
pear. 

f. Use of semi-colons — This is a restriction which, 
when not observed, could cause errors in the CREF 
table. It is recommended that the user follow 
these suggestions when preparing source files to 
insure a proper CREF listing. 

1. Semi-colons should not be used on lines 
with pseudo-ops. In particular, a com- 
bination such as the following must not 
be used: 



*3j 

TEXT %ERROR% ; TAD [42 

In this case, CREF does not process the 
page zero literal properly. A literal 
is generated which is derived from the 
expanded TEXT message. No error message 
is generated, but the literal table entry 
is meaningless. 
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2. When using conditional code a good rule to 
observe is to not use semi-colons inside 
conditional code. For example: 

EXOR = 

IFNZRO EXOR <CLA;TAD B; HLT /ERROR> 

/THIS IS THE NEXT LINE PAST IFNZRO 

The conditional code is not assembled but 
CREF does not realize that and does try to 
process the bracketed instructions. As a 
result of these semi-colons, extra symbols 
may be processed and some valid references 
missed. If the code had been assembled, 
however, CREF would operate properly. 

There are two solutions to this restriction: 

Write straight line code: 

EXOR = 

IFNZRO EXOR < 

CLA 

TAD B 

HLT ERROR 

> 

or use XLIST around conditional code, in the 
above example: 

IFZERO EXOR <XLIST> 

IFNZRO EXOR <CLA;TAD B ; HLT/ERROR> 

IFZERO EXOR <XLIST> 

XLIST turns off the listing if the code does 
not assemble and turns it back on after the 
conditional code. 

h. Formats — There are several output formats that can be 
used in generating a PALS listing file: 

/T Form feeds converted to carriage return/ 
line feeds 

/H No headings or form feeds generated 

/D DDT compatible symbol table is generated. 

For best results with CREF, none of these switches _ should 
be used. This generates a heading and form feeds in the 
output. CREF automatically converts form feeds to carriage 
return/line feeds if output is to the Teletype. 
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F.1.5 CREF Error Messages 

CREF errors are non-recoverable errors, and control returns 
to the Keyboard Monitor through 07605 (no core saved) . CBEF 
is not restartable and typing START results in 



NO! ! 



being printed as a reply. 



Error Message 
SYM OVERFLOW 

ENTER FAILED 

OUT DEV FULL 

CLOSE FAILED 
INPUT ERROR 
DEV LPT BAD 

2045 REFS 

HANDLER FAIL 



Meaning 

More than 896 (decimal) symbols and liter- 
als were encountered. 

Entering an output file was unsuccessful, 
possibly output was specified to a read 
only device. 

The output device is full (directory de- 
vices only) . 

CLOSE on output file failed. 

A read from input device failed. 

The default output device, LPT, cannot be 
used as it is not available on this system. 

More than 2044 (decimal) references to one 
symbol were made. 

Fatal error on output. Can occur if either 
the system device or the selected input de- 
vice is write locked. 
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F.2 LIBSET (DEC-P8-SYXB-PB) 

LIBSET, the FORTRAN Library Setup program, creates a library 
of subroutines from the relocatable binary output of SABR. 
These library files can be quickly and efficiently scanned by 
the Linking Loader saving a great deal of time in loading 
frequently used subroutines. How the LOADER uses relocatable 
library files, including automatic loading the LIB8.RL file 
and the /L option, is described in the 8K Programming System 
User's Guide . 

F.2.1 Loading, Calling, and Using LIBSET 

The LIBSET program is available from the Program Library on 
binary paper tape CDEC-P8-SYXB-PB) . In order to load LIBSET, 
place the binary tape into the reader and load as follows : 

.R ABSLDR 
*PTR: = 1260j3$ 

where the character $ indicates typing of the ALT MODE key. 
When the i character is printed, type any keyboard character 
to initiate reading of the paper tape. When reading is com- 
pleted, the Keyboard Monitor responds with another dot. Type: 

.SAVE SYS: LIB SET 
and LIBSET is saved on the system device. 
To call LIBSET from the system device, type: 

•R LIBSET 
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in response to the dot printed by the Keyboard Monitor. The 
Command Decoder then prints a star at the left margin of the 
teleprinter paper and waits to receive a line of input. The 
general form of input required to build a library file is: 



*output<( input file list) 
* (additional input f iles) $ 



No more than nine input files are allowed on any one line, but 
several input lines can be entered. The last input line must 
end with the user typing the ALT MODE key (which echoes as $) . 
Only the first line can contain an output file. If no output 
file is specified a file named LIB8.RL is created on the sys- 
tem device. The assumed extension for both input and output 
files is .RL. 



NOTE 

Files output from LIBSET are in a special re- 
locatable library format and must not be copied 
with the /B option in PIP. Instead they should 
be copied by PIP in image (/I) mode. 



TABLE F-2 

LIBSET OPTIONS 

Option Code Meaning 

/S The /S option means that all input files on a 

line are to be regarded as containing more 
than one relocatable binary file. (This is 
analogous to the /S option in ABSLDR. ) 



NOTE 

If /S is used on a line that contains no in- 
put files, input from PTR: is assumed. 



F.2.2 Examples of LIBSET Usage 
Example 1 ; 

*DTA2iSUBS<DTAl:SUBl,SUB2,SUB3,PTR; 
't' *SYS : FUNCl , FUNC 2 . V5 $ 
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This example creates a relocatable library file on DTA2 named 
SUBS.RL. This library will contain six FORTRAN (or SABR) sub- 
routines built by combining the relocatable binary file SUBl.RL, 
SUB2.RL, and SUBS.RL from DTAl together with one relocatable 
binary paper tape (note the i printed by PS/8 before loading 
from PTR:) and the files FUNCl.RL and FUNC2.V5 from the system 
device. 

Example 2 ; 

* AS IN, ACQS ' 
*/S$ + 

Since no output file was specified this example creates a 
relocatable library file LIB8.RL on the system device. This 
produces a new FORTRAN Library including the subroutines con- 
tained in the files ASIN and ACQS on device DSK, and several 
subroutines combined on a single paper tape loaded from the 
high-speed reader. 

F.2.3 Subroutine Names 

It is important to distinguish between the PS/8 file name of 
a relocatable binary program and its assigned Entry Point Name. 
The file name has meaning only to the Command Decoder, the 
Entry Point Name (or Names) are the true subroutine names that 
are meaningful to the LOADER. 

Further details on the format of relocatable binary files and 
relocatable library files can be found in Appendix A. 

F.2.4 Sequence for Loading Subroutines 

LIBSET can combine files in any sequence to form a relocatable 
library file. However, the subroutines in any single library 
are loaded by the LOADER in the order in which they were origin- 
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ally specified to LIBSET. Therefore, it is important to 
make sure that subroutines are specified in order of size, 
with the largest subroutine being loaded first. If this is 
not done, cases can occur in which insufficient core is avail- 
able in any single field to load a large subroutine, whereas 
space would have been available if the subroutine had been 
loaded earlier. 

F.2.5 LIBSET Error Messages 

All errors are fatal. LIBSET recalls the Keyboard Monitor 
upon encountering any of the following error conditions. 
LIBSET must be rerun in order to try again. 



Error Message 



Meaning 



BAD FORMAT OR CHECKSUM - TRY AGAIN Error in reading relocat- 
able binary file. 



ERROR WHILE WRITING OUTPUT FILE 

INPUT ERROR 

LIBRARY DIRECTORY OVERFLOW 



Fatal output error occurred. 

Parity error on input. 

Too many subroutines were 
specified. Every subrou- 
tine name in the input file 
requires four words, and 
every relocatable binary 
file read requires two words. 
If the total number of words 
exceeds 250, the library 
must be split into two separ- 
ate files. 
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Additional Information 

Words, 1-4, 1-5, 2-9, D-14 
Alphanumeric options, command 

decoder, 3-3 
ASCII 

character codes, E-4 

files, A-5 
ASSIGN entry, B-4 
asterisk symbol (*), 3-1, 3-10 
Auto-index registers, D-13 



Binary files, A-5 

Blocks 

core control, 1-5 
DEC tape, 1-3 
LINCtape, 1-3 
logical, 1-3 
physical, 1-3 
standard size, 1-3 



Calling 

command decoder, 3-4 

command decoder special mode, 3-1 

CREF, F-1 

device handlers, 4-1 

USR and device handlers 
from SABR code, D-18 

User Service Routine, 2-1, 2-3 
Card Reader handler modifica- 
tion, D-2 
Card Reader (CDR) operations, 4-7 
Carriage return/line feed sup- 
pression in FORTRAN, D-5 
CDF instructions, 2-2 
CDR, see Card Reader 
CHAIN function, 2-4, 2-13, 2-14 

core area alteration, 2-14 

data passing, 2-14 

monitor error, 2-13 
Character codes and conventions, E-1 

ASCII, E-4 
Characters, lower case, E-1 
Checksum errors, 5-10 
CIF instructions, 2-2 
Circumflex, E-1 
CLOSE function, 2-3, 2-10, 2-11, 

2-12, A-3, D-14 
Code relocation, D-9 
Command decoder subroutine , 1-2 , 
3-1, D-2 

calling, 3-4 

command line format, 3-1 

conventions, 3-1 



error messages, 3-3, 3-4 

errors, C-5 

example command line, 3-8 

input file format, 3-2, 3-3 

input files, 3-6 

legal device names, 3-3 

option table, 3-7 

output file format, 3-1, 3-2 

output files, 3-5 

special mode, 3-9, 3-10 

tables, 3-5 

termination, 3-3 
Command line format, 3-1 
Components, PS/8 system, 1-1 
Conditional assembly of CONFIG, 5-1 
CONFIG, D-2 
CONFIG. PA source file, 5-1 

conditional assembly, 5-1 

device handler code, 5-3 

optional device parameters, 5-3 

other options, 5-5 

system device selection, 5-2 
Control characters, E-2 , E-3 
Conversion PS/8 DECtapes to PS/12 

LINCtapes, D-10 
Co-resident handlers, 5-10 
Core 

area, CHAIN, 2-14 

image (.SV format) files, A-6 

segment doublewords format, A-7 

size PDP-8 computers, D-7 

size, subroutine to determine, D-8 
Core control block, 1-5,-6,-7, A-6 

format, A-6 

Job Status Word, 1-5, 1-6 

starting address, 1-5, 1-6 
CREF, Cross Reference Program, F-1 

calling and loading, F-1 

error detection, F-6 

error messages, F-8 

examples, F-2, F-3 

formats, F-7 

options, F-2, F-3 

pseudo-ops, F-5 

restarting, F-8 

restrictions, F-6 

using, F-1 
CTRL/C, 1-1 

Current directory segment, re- 
writing, D-14 
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Data field, 2-2 

Data passing, CHAIN, 2-14 

DATE 

command, 1-5 

system word, 1-5, 2-9 

system word (FORTRAN) , D-6 
DEASSIGN corainand, B-4 
DECj2f29 standard card code, D-2 
DEC026 standard card code, D-2, D-4 
DECODE function, 2-4, 2-12, 2-13, 
3-4 

monitor error, 2-13 

normal return, 2-13 
Decoder, Command see Command 

decoder subroutine 
DECtape to LINCtape conversion, D-10 
DECtape 

operations, 4-7 

system, 5-3 

system building, 5-7 
DEVICE pseudo-op, 1-8 
Device control word table, B-6 
Device dependent operations, 4-4 
Device handler 

adding new, 5-7 

call format, 4-2 

call sequence, 5-8, 5-9 

code, 5-3 

editing into CONFIG, 5-12 

errors, 5-9 

information table format, B-5,-6 

loading, 2-5, D-11, D-12 

residency table, B-5 

standards, 5-9, 5-10 

writing, 5-8 

utilization, 1-2 
Device handler usage, 4-1 

calling device handlers, 4-1, 4-2 

card reader, 4-7 

device dependent operations, 4-4 

file structured devices, 4-7 

high-speed paper tape punch, 4-5 

high-speed paper tape 
reader (PTR) , 4-5 

line printer, 4-6 

TTY, 4-4 
Device length table, B-7 
Device parameters, optional, 5-3 
Devices, file structured, 1-3 
Device names, B-4 

assumed, D-2 

command decoder, 3-3 

and numbers, 1-7, 1-8 

selection, 5-13 



DF32 Disk system, 5-2 

operations, 4-7 
DIRECT option, 5-5 
Direct calling sequence, USR, 2-2 
Directory block 

example, A-9 

structure, A-1 
Directory 

entries, A-2 

file, A-1 

fragmentation. A- 4 

sample, A-4 

segment, rewriting current, D-14 
DSK, Default file storage device, D-^ 



Editing device handlers into 

CONFIG, 5-12 
Empty file, 1-4, A-2 
End-of-file condition, command 

decoder, 3-7 
ENPUNCH, D-8 

ENTER function, 2-3, 2-8, 2-9, 3-6 
D-14 

error return, 2-9, 2-10 

normal return, 2-9 
ERROR function, 2-4, 2-14 
Error messages 

command decoder, 3-3, 3-4 

CREF, F-8 

LIBSET, F-12 

Monitor, 2-15 

summary, C-1 
Error return 

CLOSE, 2-11, 2-12 

device handler, 4-3 

ENTER, 2-9 

FETCH, 2-6 

INQUIRE, 2-18 

LOOKUP, 2-7, 2-8 
Errors 

checksum, 5-10 

command decoder, C-5 

CREF, F-6 

keyboard monitor, C-4 

parity, 5-10 

USR, C-2 
Example 

command line, 3-8 

reconfiguration, 5-6 
Exit, system, 1-1 
Extensions, file names and, 1-2 
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FETCH conunand, D-11 

FETCH function, 2-3,-4,-5,-6, 4-1 

File 

formats, A- 5 

number, A-3, A-4 

size, A-3, A-4 

starting block, A-3 
Files, 1-2 

ASCII, A-5 

core image (.SV format), A-6 

data format, 1-2 

directories, 1-4 

empty, 1-3, A- 2 

multiple input, D-11 

names and extensions, 1-2 

permanent, 1-4, A-2 

relocatable FORTRAN library. A- 8 

system device (SYS:), 1-3 

tentative, 1-4, A-3 

types, 1-3 
FILENAME pseudo-op, 1-8 
File structured devices, 1-3 
File structured devices operation 

4-7, 4-8 
File structures, A-1 

ASCII, A-5 

binary , A-5 

directories, A-1 

formats, A-5 

relocatable FORTRAN library. A- 8 
Formats 

command decoder option table, 3-7 

CREF, F-7 

file data, 1-2 
FORTRAN 

carriage return/line feed sup- 
pression, D-5 

8K, D-12 

library file, relocatable, A-8 

Library Setup program, F-9 

program system date, D-6 

run time I/O routines, 5-4 



Halt 

LOADER program, C-2 
system, C-1, C-2 
High speed paper tape punch (PTP) 

operation, 4-5, 4-6 
High speed paper tape reader 
(PTR) operation, 4-5 



Indirect calling seauence USR, 2-2 



Information words, additional, 1-4, 

1-5 
Input file format, command 
decoder, 3-2, 3-3 
format, 3-6 
Input tables, command decoder, 3-7 

special mode, 3-10 
INQUIRE function, 2-4, 2-17, 2-18 
Instruction field, 2-2 



Job Status Word, 1-6 
format, A-6 



Keyboard monitor, 1-1 
calling, 1-1 
errors, C-4 



LAP (Leave Automatic Paging 

pseudo-op) , D-16 
Layout of resident program, B-2 
Layout of system, B-1 
LIBSET, FORTRAN Library Setup 
Program, F-9 

calling, F-9 

copying LIBSET files, F-10 

error messages, F-12 

examples, F-10, F-11 

loading, F-9 

loading sequence, F-11 

options, F-10 

subroutine names, F-11 

using, F-9 

LINCSYS, 5-2, 5-3 
LINCtape 

handlers, 5-4 

operation, 4-7 

system building, 5-7 
Line printer (LPT) operation, 4-6 
LOADER program halt, C-2 
Loader control words, A-8, A-9 
Loading 

CREF, F-1 

device handlers, D-11 

device handlers dynamically, D-12 
Logical end-of-file, device 

handler, 4-3 
LOOKUP function, 2-3, 2-7, D-14 
Lower case characters, E-1 
Low-speed paper tape, 5-4 
LP12 line printer, type 645, 5-4 
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Masking, 1-2, 4-1 
Maximum number of files, A-4 
Maximum size of file, A-4 
Monitor error, 

CHAIN, 2-13 

CLOSE, 2-13 

ERROR, 2-15 
Multiple input files, D-11 



Names 

device, 1-7, 1-8, B-4 

file, 1-8 
Normal return, 

CLOSE, 2-11 

ENTER, 2-9 

FETCH, 2-6 

INQUIRE, 2-17, 2-18 

LOOKUP, 2-7 

RESET, 2-19 
Null files, 3-3 
Number and size of file, A-3 
Numbers, device, 1-7, 1-8 
Number symbol (#) , F-5 
Niomeric options, command 
decoder, 3-3 



ODT breakpoint, CHAIN, 2-14 
ODT breakpoint usage, D-13 
Operating command decoder in 

special mode, 3-10 
Optional device parameters 

CONFIG, 5-3 
Options , command line 
alphanumeric, 3-3 
numeric, 3-3 
Option tables, command decoder, 3-7 

special mode, 3-10 
Output files, command decoder, 3-5 

format, 3-1, 3-2 
Output table, command decoder 
in special mode, 3-10 



Program starting address, 1-6 

format, 1-6 

START command, 1-6 
PRTC12-F program, D-10 
Pseudo-ops, CREF 

PAL8, F-5 

SABR, F-5 
PTP see High-speed paper tape 

punch 
PTR see High-speed paper tape 

reader 
PUNCH feature, D-9 



R command. A- 7 
Record, definition of, 4-1 
Record transfer, 4-1 
Reconfiguration, 5-1 

adding new device handlers, 5-7 

building system on DECtcipe or 
LINCtape, 5-7 

editing device handlers into 
CONFIG, 5-12 

example, 5-6 

writing device handlers, 5-8 
Relocating code, D-9 
RESET function, 2-4, 2-18, 2-19 

deleting tentative files, 2-19 

normal return, 2-19 
Resident program layout, B-2 
Restarting CREF, F-8 
Restrictions 

command decoder in special 
mode, 3-10 

device handlers, 4-3 

USR calls, 2-2 
Rewriting current directo3:y seg- 
ment, D-14 
RF)2f8 disk system, 5-2 

operations, 4-7 
RK8 disk system, 5-2 

operations, 4-7 
RUN command. A- 7 



PAGE pseudo-op, D-16 
PAL8, CREF pseudo-ops, F-5 
Parity 

codes, E-1 

error, device handler, 4-3 

errors, 5-10 
PDP-12 LINCtape system, 5-2 
Permanent device name table, B-3 
Permanent file, 1-4, 2-10, A-2 
Permanent file entry, 2-7 



/S (compress device) option, B-8 
SABR 

code, D-16 

code, calling USR and device 
handlers, D-18 

CREF pseudo-ops, F-5 

programming notes, D-16 
Sample directory, A-4 
SAVE command, 1-5, 1-6 
Segment header, A-1 
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Semicolons, CREF, F-6, F-7 
Special mode of the command de- 
coder, 3-9, 3-10 
START command, 1-6, 1-7 
Storage space USR area, D-13 
.SV (core image) file, 1-5, A-6 
Subroutine to determine core 

size, D-8 
Summary USR functions, 2-3 

CHAIN, 2-13 

CLOSE, 2-10 

DECODE, 2-12 

ENTER, 2-8 

ERROR, 2-14 

FETCH, 2-4 

INQUIRE, 2-17 

LOOKUP, 2-7 

RESET, 2-18 

USRIN, 2-15 

USROUT, 2-16 
Syntax error, command line, 3-3 
SYS, D-2 
System 

building on DECtape or LINC- 
tape, 5-7 

DATE, 1-5, 2-9 

Date word, 1-5 

Date word, FORTRAN, D-6 

device selection, CONFIG, 5-2 

device (SYS:), 1-3 

device tables, B-3 

exit, 1-1 

layout, B-1 

scratch blocks 



Up arrow character ( f ) , 5-5 
User device name tables, B-4, B-5 
USR (User Service Routine) 1-2 

area storage space, D-13 

calling, 2-1 

direct calling, 2-2 

ERROR, C-3 

function summary, 2-3 

indirect calling, 2-2 

restrictions, 2-2 
USRIN function, 2-3, 2-4, 2-15, 2-16 
USROUT function, 2-4, 2-14, 2-16 



Write lock error, device handler, 
4-3 



/X option, CREF (PALS) , F-6 



B-1, 
software components , 



B-2 
1-1 



Tables 

permanent device name, B-3, B-4 

system device, B-3 

user device name, B-4, B-5 
Table lookup example, 5-11 
Teletype (TTY) operation, 4-4, 4-5 
Tentative file, 1-4, 2-10, A-3 

deletion, 2-19 

entry, 2-8 
Termination, command decoder, 3-3 
Terminology, 1-1 
TTY see Teletype 
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